Updating Documentation

The documentation consists of the User's Guide and Programmer's Guide, written in LaTeX (and converted to web pages with LaTex2HTML) and tutorials and other guides written in HTML.

Directory Structure

root
    /bin
    /coding_standards
    /css
    /production_manual
    /programmer_manual
        /html (generated)
        /tex
    /tutorials
    /user_manual
        /html (generated)
        /images
        /tex

Updating the User and Programmer Manuals

Overview

The User and Programmer manuals are documented in LaTeX and then converted into html via the latex2html utility. This makes the documentation easy to edit so as to include formulae, tables, etc. using familiar LaTeX syntax. Hypertext links both within each document and to external documents or websites can be made using special LaTeX commands.

Structure

The LaTeX versions of the documentation are found in the subdirectories doc/user_manual/tex and doc/programmer_manual/tex, respectively. In each, the main document that specifies the "chapter headings" has a .tex extension, with all subsequent individual included sections having a .inc_tex extension. Any associated images to be included should be placed in the /images subdirectories for each manual.

Labels and Links

In each file of the form FName.inc_tex, the first line is \label{FName}. This provides a label that can be used as a target for links. Additional labels can also be used elsewhere in the document where convenient, but should have unique names.
Links to such labels are made internally (i.e. from elsewhere within the manual) using the syntax: \htmlref{<highlighted text>}{FName}. In addition, a facility has been created to allow links to these labels to also be made from external pages or documents as well. For this, the syntax should be: \htmladdnormallink{<highlighted text>} {<manual subdirectory>/html/external/<label>.html}.
On the other hand, links to external documentation can be made by invoking \htmladdnormallink{<highlighted text>} {<url or file location>}.

Format

Any \section{} or \subsection{} commands etc. that are included in the file will result in a separate html page being generated in association with cascaded links. Hence, for readability, it may sometimes be more convenient to instead use large font sizes etc. to denote sections if you wish the information to be displayed on a single page.

Compiling

After editing is complete, go to the rat directory and run scons doc. This will invoke latex2html for both user and programmer manuals and place the output files in the respective /html subdirectories, generate "redirection" files used to externally access links to labels and place these in the appropriate /external subdirectories, and will then update the database used in the companion to perform keyword searches in the documentation. NOTE: The build requires a copy of latex2html, not included in snoing. OSX users installing with homebrew will need to run: brew install --env=std latex2html for the build to be successful.

Committing Changes

To commit your changes to the official documentation, commit them first to your own fork of the snoplus/rat repository on GitHub, then submit a pull request. For more information on using GitHub, see SNO+-doc-1462.

Online Documentation

Every time a change is made to the official repository (github.com/snoplus/rat), the HTML documentation at http://snopl.us/docs updates automatically.

Requirements for Documentation

Be written simply and intelligibly
Should be understandable to someone who hasn't worked on that code. Not just an aide to the memory of the author.
Any new features or major updates to the code should be documented
Any old feature being removed should also be removed from the documentation
Include links to the tutorials and example macros where relevant
Contain relevant working links to DocDB, etc...

Updating Doxygen Code Documentation

The generation of code documentation is accomplished using Doxygen, which is run starting at the rat subdirectory with the output targeted for the dox subdirectory. This can be separately generated by issuing the command "scons dox" from the rat directory.
The formatting for Doxygen used in RAT can be found in the Coding Standards and Style Guide, in Section 2.2 on the File Header Comments and 2.15 on Commenting Code.

Home