GENESIS: Documentation

Related Documentation:

Create a New Document

Introduction

The GENESIS Documentation System is fully automated with versioning under the control of monotone. To learn more about monotone and its use by GENESIS see Version Control and to learn more about the levels of GENESIS documentation see Documentation Overview. This document assumes that you are familiar with that material.

Here, we introduce some of the flexibility, features, and requirements of the GENESIS Documentation System. We describe the location of source files within this system, the contents of a documentation folder/directory, and how to create a new document. UNIX shell command line utilities are available to query and maintain the GENESIS Documentation System as a filesystem based database of documents.

To learn how to add a new document to the GENESIS version control system see Version Control. Once a document is under version control and identified with the correct tags (see below) it can be automatically published from your local computer to the GENESIS website (www.genesis-sim.org) to be available for other members of the GENESIS community.

Location of GENESIS Documentation

Following a Developer Installation the documents that make up the GENESIS Documentation System are located in your local workspace. The default location of your local workspace is:

    ~/neurospaces_project/userdocs/source/snapshots/0

The source materials for individual GENESIS documents are located in uniquely named folders/directories in your local workspace. One of the directories in the workspace is named NewDocument. This directory and the files it contains provide the templates for a generic GENESIS document. The files included by default are descriptor.yml and NewDocument.tex, and a sub-directory named figures (see also GENESIS source code directory layout).

The Default YAML Descriptor File

The name of the descriptor file descriptor.yml should not be changed. The default contents of this file include: attributes (terminated by a colon) and tags (indicated by a hyphen), for example:

---  
comment: Optional comment.  
description: Briefly describe document contents here.  
document name: Insert a user readable document name here.  
tags:  
  - genesis3  
  - level2  
  - published

Two important attributes are not included in the default descriptor.yml file, but may be added as required:

The Default Documentation Source File

Source files for the GENESIS Documentation System are currently produced with the LATEX typesetting package (see www.latex-project.org). It is planned that Microsoft Word (.doc format) and OpenOffice (.odt, ODF format) file formats will also be automatically recognized by the GENESIS Documentation System.

The default LATEX documentation source file NewDocument.tex in the NewDocument folder can be compiled to produce a readable PDF file. It gives help and examples for colorizing text, generating static hyperlinks to local and remote documentation, and how to insert a figure into your documentation.

The Figures Folder

This directory contains any figures that your new document source file may include. The name of this folder should not be changed.

Create a New Document

There are four simple steps to the creation of a new document within the GENESIS Documentation System.

  1. Create document: To automatically create one or more new document template structures, simply envoke the userdocs-create script at a terminal command line prompt and give the name of the document you wish to create as an argument:
       userdocs-create <my-document>

    This command creates a new document folder/directory and its sub-directories by copying the template NewDocument file and assigning the given document name to both the documentation folder (here, for example, it would be my-document) and the default documentation file it contains (here, my-document.tex). It also inserts a description and a document name into the descriptor.yml file.

    You can also specify multiple document names to create a series of documents:

       userdocs-create <my-document1> <my-document2> <my-document3> . . .

    Important: It is a requirement of the GENESIS Documentation System that the names of the descriptor file descriptor.yml and the directory figures located in the document folder should not be changed.

    For more details see Manual Document Creation. The remaining steps in document creation are currently manual.

  2. Add Related Document Hyperlinks: Hyperlinks to one or more related documents are by default located at the beginning of each document source .tex file following the Related Documentation heading. There are two ways to add links here:
  3. Update the descriptor.yml file: Each directory/file in the GENESIS Documentation System is tagged on the basis of its content, for example:

    1. The GENESIS version: This tags the version of GENESIS that the document refers to, e.g. -genesis3.
    2. Level of the GENESIS document: This must be one of the seven levels of the GENESIS Documentation System, which include:
      • -level1 (introductory documentation)
      • -level2 (user/developer documentation)
      • -level3 (autogenerated documentation)
      • -level4 (autogenerated technical documentation)
      • -level5 (autogenerated algorithm documentation)
      • -level6 (autogenerated api documentation)
      • -level7 (inline source code documentation)

      Important: When creating a new document, the default tag (-level2) in the associated descriptor.yml file should be replaced with a tag from the above list that identifies the correct level of the document.

      For more on the levels of the GENESIS Documentation System see the Documentation Overview.

    3. Tag Appearance of Document Name in Contents Index: A document name (given by the documentname: attribute) will not appear in the documentation contents list unless one of the -contents-level1-contents-level7 tags is present in the associated descriptor.yml file. The presence of this tag results in the document name being placed in alphabetical order in the contents page of the level specified by the tag. If you do not want the name of the document to appear in the contents page you should remove this tag. This functionality allows one or more documents to be hyperlinked from a summary document (see particularly Level 1 and 2 documentation) without the name of the hyperlinked document(s) also appearing in the contents page of the given level.
    4. Insert “Related Document” hyperlink tags: To link a new document (Referring Document in following figure) to another document (Referenced Document in following figure) under its Related Documentation section, place the appropriate tag after the tag construct at the head of the Referring Document and place the same tag in the descriptor.yml file of the Referenced Document. The following figure illustrates these relationships.
      PIC

    5. Tag document origin: If the document has been created from one located on the Neurospaces wiki then a --wiki tag should be inserted in the descriptor.yml file.
    6. Tag document status: For a given document to be part of the documentation version control system and the GENESIS Documentation System, it must be in a documentation folder along with a descriptor.yml file that contains only one of either the -draft, -local, or -published tags. Note: The -published tag in the descriptor.yml file associated with your new document should be replaced with the -draft tag while you are working on the document to prevent it being published to the GENESIS website.

      Precedence of publication related tags: Three tags control publication of documents within the GENESIS Documentation System. They are interpreted in a hierarchical manner, such that the presence of the -draft tag along with either the -local and/or -published tag will prevent the document from being included into a build/update of the Documentation System. Alternatively, a document will not be published to be browser viewable in the absence of either the -local or -published tag. So if documentation is (not) appearing where you expect after an update, it is a good idea to check the publication tags in the descriptor.yml file.

      • -draft: The presence of this tag in the descriptor.yml file associated with a document will prevent the document from being published, i.e. viewable within a browser. For a document to be publishable, the -draft tag must be replaced with either the -local or the -published tag.
      • -local: This tag indicates that a document will be included into any local build of the the GENESIS Documentation System. The presence of this tag means that a document will be browser viewable on (a) local machine(s), but will not appear as a ‘published’ document on the GENESIS web site at http://genesis-sim.org. This tag is useful to developers for checking documentation prior to publication on the web via the GENESIS web site and can be used to control who can view documentation locally.
      • -published: The presence of this tag in the descriptor.yml file will cause the associated document to be published to the GENESIS Documentation System on the GENESIS web site, as long as neither the -draft nor the -local tags are present in the same descriptor.yml file (see next item). Similarly, absence of the -draft tag but presence of the -local tag will prevent publication of a document to the GENESIS web site even if the -published tag is present.

      Tags in the descriptor file currently recognized by the documentation build system include:

        tags:  
          - contents-level1  
          - contents-level2  
          - contents-level3  
          - contents-level4  
          - contents-level5  
          - contents-level6  
          - contents-level7  
          - draft  
          - local  
          - published  
          - obsolete  
          - html  
          - pdf  
          - png  
          - ps  
          - mp3  
          - wav

      Other useful tags include:

          - genesis2  
          - genesis3  
          - level1  
          - level2  
          - level3  
          - level4  
          - level5  
          - level6  
          - level7  
          - wiki  
          - create  
          - introduction  
          - tutorial  
          - document

      Note: User supplied tags not recognized by the documentation build system may still be useful for local control and sorting of documentation. Importantly, when adding your own tags remember that the interpretation of the descriptor.yml file by the GENESIS Documentation System is sensitive to white space and indents.

  4. Update the figures folder: Place any figures or images, etc that your source document file contains in the figures directory.

Incorporate References in Your Document

The GENESIS Documentation System currently supports BibTeX by default. The two LATEXcommands at the end of the NewDocument template enable this functionality. They are:

   \bibliographystyle{plain}  
   \bibliography{../../../tex/bib/g3-refs.bib}

These commands allow you to define a citation style for your references and give the location of a file that complies with the BibTex file format requirements and contains your bibliography. Currently, the default name of this file is g3-refs.bib. It contains all the references for the GENESIS Publication System.

Incorporate a Pre-existing Document, File, or Video

The GENESIS Documentation System recognizes a number of different file formats. The purpose is to allow preexisting documentation to be directly included without having first to be converted to the LATEX format.

To incorporate a pre-existing document into the GENESIS Documentation System:

  1. Include a tag in the descriptor.yml file in the document directory. Currently, the following file format tags are recognized (Note. No tag is necessary for either LATEX files as the .tex file name suffix is the default for the GENESIS Documentation System or .eps files in the figures folder):
  2. Place the document file in the document directory (NOT the figures sub-directory).

It is also possible to incorporate audio and video files as part of documentation. Currently recognized audio file format tags include:

To incorporate video into a GENESIS document:

  1. Create an account with a video sharing website, e.g. YouTube.
  2. Upload your video(s).
  3. Embed a link to the video(s) into the document describing their contents. See NewDocument, for further details.

Note: With document incorporation (c.f. creation) the document to be included is located in the <document-name> directory and NOT the figures subdirectory.

Document Version Tracking and Control

To learn more about document version tracking and control in the GENESIS Documentation System, see Version Control.

Document Hyperlink Checking

The validity of the hyperlinks embedded in GENESIS documentation (see NewDocument) are checked by userdocs_cron each time the GENESIS Documentation System is rebuilt. The output of this check can be viewed at www.genesis-sim.org/userdocs/webcheck/badlinks.html.

Webcheck can also be run locally to check hyperlinks. When run in the

   ~/neurospaces_project/userdocs/source/snapshots/0

directory, the command makewebcheck will produce a report in

   ~/neurospaces_project/userdocs/source/snapshots/0/html/htdocs/neurospaces_project/userdocs/webcheck/

Document Publication

To learn more about the automated publication of documents in the GENESIS Documentation System, see Publication.