Documenting Guidelines

Following the guidelines below when documenting to the project would be appreciated

Building the documentation

The documentation is built using Sphinx.

The first thing to do when trying to build the documentation is to setup the environment.

We advise you to synchronise the Openschc project in two separate directories. One for the source code synchronised with the branch you want to build and the other with the gh-pages branch on which the documentation will be built.

An example on how to do it

$ mkdir openschc_docs
$ git clone https://github.com/openschc/openschc.git
$ cd openschc_docs
$ git clone https://github.com/openschc/openschc.git html
$ cd html
$ git checkout gh-pages
$ cd ../..

$ tree
.
├ openschc
│   ├ _static
│   ├ docs
│   │   ├ _build
│   │   ├ _static
│   │   └ _templates
│   └ src
└ openschc_docs
    ├ doctrees
    └ html
        ├ _images
        ├ _sources
        └ _static

An important thing to do before building the documentation is to indicate to Sphinx where to build the documentation. This information is provided in the Makefile under the docs folder:

$ head -n 10 Makefile
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS    =
SPHINXBUILD   = sphinx-build
SPHINXPROJ    = OpenSCHC
SOURCEDIR     = .
BUILDDIR      = ../../openschc_docs

Another good thing to do is add the Makefile to your .gitignore file in order to prevent your changes to be forced on everyone:

$ pwd
openschc/docs
$ echo "docs/Makefile" >> ../.gitignore

Then you can build the documentation (in the master branch or your own development branch):

$ pwd
openschc/docs
$ make html

Normally the documentation will be built automatically, you can open it in your browser or push it to your remote gh-pages branch to publish the website

Syntax

Sphinx’s default syntax is called ReStructuredText. The documentation provides a syntax guide.