GENESIS: Documentation

Related Documentation:

Documentation Tools

Introduction

Here we describe a number of UNIX shell command line utilities to query and maintain the GENESIS Documentation System as a filesystem based database of documents. Note that these tools are not used to search the contents of the documents. The GENESIS and Neurospaces websites provide this type of user-functionality.

Available Tools

Typing userdocs- in a bash system command shell followed by striking ¡tabż key twice will show all the available commands to query and maintain the GENESIS Documentation System.

Each command has a help page that shows all the available options to the invoked command. This page isinvoked by the –help argument (for example userdocs-build –help).

Here we summarize the function of all the commands.

Example

This is an interactive tutorial with examples that show typical usage of the tools mentioned above.

To learn about how to build individual documents:

$ userdocs-build --help  
 
 
userdocs-build: build documentation and prepare them for web  
publication.  Arguments on the command line are taken as documents  
that need to be build.  If no arguments are given, all documents will  
be build.  
 
synopsis:  
    /usr/local/bin/userdocs-build <document name1> <document name2> ...  
 
options:  
    --check           check documentation filesystem correctness.  
    --dry-run         print what documents would be build without actually building them.  
    --email           send the built document to this email address, repeat for each receiver.  
                      NOTE: see http://www.amirwatad.com/blog/archives/2009/03/21/send-email-from-the-command-line-using-gmail-account/ as an example of a local configuration of your MTA.  
    --help            print usage information.  
    --parse-only      only execute parse commands, without actually building documentation.  
    --regex           selects documents by name (default is all).  
    --report-output   report what output has been generated.  
    --report-tags     report the tags associated with the selected documents instead of building the documents.  
    --set-name        select a document set (builtin default is userdocs).  
    --tags            process the documents with these tags, multiple tags options may be given.  
    --version         give version information.  
    --v|verbose       tell what is being done, specify multiple times to get more feedback.  
 
example usage:  
    /usr/local/bin/userdocs-build documentation-homepage  
    firefox -new-window html/htdocs/neurospaces_project/userdocs/documentation-homepage/documentation-homepage.html  
 

To display all the tags currently in use:

$ userdocs-build --report-tags  
---  
all_processed_tags:  
  - abstract  
  - contents-level1  
  - contents-level2  
  - contents-level3  
  - contents-level4  
  - contents-level5  
  - contents-level6  
  - contents-level7  
  - developer  
  - do-nothing  
  - doc  
  - genesis2  
  - genesis3  
  - gshell-interactive  
  - introduction  
  - level1  
  - level2  
  - level3  
  - level5  
  - pdf  
  - poster  
  - published  
  - redirect  
  - related-add-functionality  
  - related-build-debian  
  - related-cbi-architecture  
  - related-chemesis-3  
  - related-developer-installation  
  - related-do-nothing  
  - related-documentation-system  
  - related-genesis-systems  
  - related-model-container  
  - related-notes-dave-g2  
  - related-pub-purkinje-deschutter1-conductance1  
  - related-pub-purkinje-deschutter1-morphology  
  - related-publication  
  - related-ssp  
  - related-todo  
  - related-tutorial  
  - related-workflow  
  - rst  
  - rtf  
  - rtxi  
  - tutorial  
  - userworkflow-do-nothing  
  - wiki  
  - workshop  

To learn what documents are shown on the contents page of level 1 documentation:

$ userdocs-build --tags contents-level1 --dry-run  
---  
all_documents:  
  /home/genesis/neurospaces_project/userdocs/source/snapshots/0/contents-level1: contents-level1  
  /home/genesis/neurospaces_project/userdocs/source/snapshots/0/developer-intro: contents-level1  
  /home/genesis/neurospaces_project/userdocs/source/snapshots/0/faq: contents-level1  
  /home/genesis/neurospaces_project/userdocs/source/snapshots/0/genesis-installation: contents-level1  
  /home/genesis/neurospaces_project/userdocs/source/snapshots/0/user-intro: contents-level1  

We can then build one specific document (for instance the user-intro document) with:

$ userdocs-build user-intro

Note that we do not prefix the name of the document with its directory.

To build all the documents shown on the contents page of level 1 documentation:

$ userdocs-build --tags contents-level1  
  ...  
  ...

To build all the documentation you issue the userdocs-build command by itself. This will take some time to run. The result is a directory hierarchy with html documents in your home directory ( /neurospaces_project/userdocs/source/snapshots/0/html/htdocs/neurospaces_project/userdocs/).

It is convenient to combine some of these options. For instance to learn which tags are associated with the user-intro document:

$ userdocs-build --report-tags user-intro  
---  
all_processed_tags:  
  - contents-level1  
  - genesis3  
  - level1  
  - published  

To know which tags are associated with the documents in level 1 documentation:

$ userdocs-build --report-tags --tags level1  
---  
all_processed_tags:  
  - contents-level1  
  - developer  
  - genesis3  
  - gshell-interactive  
  - introduction  
  - level1  
  - published  
  - related-workflow  
  - wiki  

To know which documents are still in draft status and thus unpublished:

$ userdocs-build --dry-run --tags draft  
---  
all_documents:  
  /home/cornelis/neurospaces_project/userdocs/source/snapshots/0/genesis-integration-with-gshell: draft  
  /home/cornelis/neurospaces_project/userdocs/source/snapshots/0/installation-studio: draft  
  /home/cornelis/neurospaces_project/userdocs/source/snapshots/0/mercurial-testing: draft  
  ...