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