GENESIS: Documentation

Related Documentation:

• Document Queries and Maintenance

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:

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:

• --- The three dashes on the first line of the file descriptor.yml are part of the YAML syntax for automated software engineering.
  Note: The meaning of the white space/indents in the descriptor.yml file is defined for YAML.
• comment: Optional comment about the documentation file, e.g. reason for being tagged -obsolete.
• description: The default file description “Briefly describe file contents here.” should be replaced with a short description of the subject matter of the documentation file. It is recommended that this file description is less than 80 characters on a single line.
• documentname: Provide a document name which gives the title of the documentation file. This name is used as a link to the given file in the GENESIS Documentation System. This name is independent of and should be more human readable than the actual name of the document file it identifies.
• tags: List of tags used to identify the current document and locate it correctly in the documentation hierarchy. The default tags include -genesis3, -level2, and -published. These tags indicate that the document is part of the GENESIS Documentation System at the level of User Guides and Documentation (Level 2) and that that the document will be published when documentation is rebuilt (see neurospaces_cron), but that in the absence of a - contents-level2 tag, the document name will not appear in the Level 2 Contents index (see below).
  • New tags may be created by adding them to the descriptor.yml file, but see below for a list of the tags currently recognized. Note: The tagging system is case insensitive to avoid tag duplication.
  • Importantly, each of the directories contents-level1 . . . contents-level7 in your local workspace contains a list of the documentation to be found at the given level. These content indices are generated automatically during a GENESIS installation, a userdocs module installation, or a GENESIS update. They provide direct links to all documents tagged for the given level of documentation.

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

• redirect: If present, this attribute is followed by a user supplied URL and automatically generates a HTTP redirect during a documentation system build. This allows documentation external to the GENESIS Documentation System to be automatically incorporated in the absence of any local documentation (with the exception of the descriptor.yml file). See HTTP redirect for an example.
• summary: If present, this attribute is followed by a short user supplied description of the contents of the document. This description will appear after the document name on the contents index page of the documentation level given by (for example here) the -contents-level2 tag.

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.

0. 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.

0. 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:
   • Hyperlinks to Manually Created GENESIS Documentation: For Level 1 and 2 documentation, this is done in the usual way with the LATEX href command. See New Document for an implementation example .
   • Hyperlinks to Automatically Generated GENESIS Documentation: Hyperlinks to the automatically generated documentation of Levels 3–7 requires a tagging construct. This is by default located at the beginning of each document source .tex file following the Related Documentation heading. The generation of these links is controlled by a tagging construct which is automatically expanded whenever the document system is rebuilt:

     % start: userdocs-tag-replace-items <related-do-nothing>      % end: userdocs-tag-replace-items <related-do-nothing>

     The default tag for this system is <related-do-nothing>, which allows a document to be created and published in the absence of any related hyperlinks.

     More than one related document hyperlink can be added to a document by the addition of tags you create that replace the default tag. For example:

     % start: userdocs-tag-replace-items <your-tag-name1> <your-tag-name2> <your-tag-name3> . . .      % end: userdocs-tag-replace-items <your-tag-name1> <your-tag-name2> <your-tag-name3> . . .

     As shown in the above example, the related tag(s) should have the following form:

     related-<your-tag-name1>

     where <your-tag-name1> is replaced by an identifier you create.

     Note: The default related document hyperlink related-do-nothing relies on a document called do-nothing.tex.

0. Update the descriptor.yml file: Each directory/file in the GENESIS Documentation System is tagged on the basis of its content, for example:
   0. The GENESIS version: This tags the version of GENESIS that the document refers to, e.g. -genesis3.
   0. 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.

   0. 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.
   0. 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.

      ---

      ---

   0. 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.
   0. 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.

0. 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:

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):
   • - eps Encapsulated postscript.
   • - pdf Portable document format.
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:

• - wav Microsoft .wav file format.
• - mp3 Digital audio encoding format.

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

directory, the command makewebcheck will produce a report in

Document Publication

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