Creating Documentation

This section describes how documentation directory trees are set up. The special case of the GoMSS Nowcast Project Documentation is described separately from Documentation in Code Repositories because the former is in a repository that contains only documentation, while documentation in code repositories is only one element of their contents.

GoMSS Nowcast Project Documentation

Version Control Repository Creation

The GoMSS Nowcast project documentation was initialized by creating a public Mercurial version control repository in the gomss-nowcast team account on the Bitbucket web service. The repository from Bitbucket was cloned:

$ cd projects/gomss-nowcast/
$ hg clone ssh://hg@bitbucket.org/gomss-nowcast/docs

Initial Files and Directories Creation

In an activated Working Environment the sphinx-quickstart command was used to create a Sphinx configuration file, conf.py, a master documentation file, index.rst for the project docs, a Makefile to control the documenation build processes, and 3 empty directories:

  • _build/ where the rendered docs produced by the build process will be stored
  • _static where static asset files such as images used in the docs will be stored
  • _templates where custom templates for the docs pages will be stored
$ source activate gomss-nowcast-docs
(gomss-nowcast-docs)$ cd docs
(gomss-nowcast-docs)$ sphinx-quickstart

The default setting values offered by sphinx-quickstart were accepted with the following exceptions:

The project name will occur in several places in the built documentation.
> Project name: GoMSS Nowcast
> Author name(s): GoMSS Nowcast Project Contributors

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version: 1
> Project release [1]: 1

Please indicate if you want to use one of the following Sphinx extensions:
...
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
...
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
...

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]: n

Sphinx Build Configuration File

The conf.py file was edited to:

  • Set configuration options that we want
  • Delete the many commented out configuration settings that described defaults that we want to use
  • Add come code to make the copyright year range automatically adjust to include future years

Please read the conf.py file and the Sphinx build configuration file documentation to learn more.

Master Documentation File

The index.rst file was edited to add a description of the project, and to start the documentation Contents section with the CONTRIBUTORS.rst file.

When the documentation is rendered to HTML the contents of the index.rst file become those of the top level index.html page.

License Choice

A Creative Commons Attribution 4.0 International License was chosen for the GoMSS Nowcast project documentation because it is a permissive license that requires attribution for use of the documentation. It is appropriate for the contents of the repository because they are primarily text rather than code.

The blob of HTML that provides the necessary license links and metadata was generated on the Creative Commons License Chooser page.

The copyright notice and license citation were added to the index.rst file as its License section.

Project Contributors File

The CONTRIBUTORS.rst file was created and text added to it to provide information about the leadership of the GoMSS Nowcast Project and a list of people who contribute to it.

Documentation Build and Preview

The command described in Building the Documentation to Preview Changes were used to do an initial build of the documentation which was previewed in a browser by opening the docs/_build/html/index.html.

Initial Version Control Commit

After correction of any typos and/or layout issue revealed by the rendered docs preview, the new documentation files were added and committed to the version control repository with:

(gomss-nowcast-docs)$ hg add
(gomss-nowcast-docs)$ hg commit -m"Init repo w/ README, license, CONTRIBUTORS, index pg & Sphinx build config."

Documentation in Code Repositories

To be written