Building the docs

To build the docs, grab a copy of the pavics-sdi repository on github:

git clone https://github.com/Ouranosinc/pavics-sdi.git

This is the repository presently storing the comprehensive documentation for the PAVICS platform. Because PAVICS processes are documented using the autoprocess directive, you’ll also need to install a few other packages that contribute services for documentation to

git clone https://github.com/Ouranosinc/flyingpigeon.git
cd flyingpigeon
git checkout pavics
make clean install
cd ..

git clone https://github.com/Ouranosinc/malleefowl.git
cd malleefowl
make clean install
cd ..

git clone https://github.com/bird-house/hummingbird.git
cd hummingbird
make clean install
cd ..

There are other requirements (sphinx and a few extensions) that can be installed using pip in Python (2 or 3):

pip install -r requirements.txt

After installing these libraries, you should be able to build the docs without errors:

cd pavics-sdi/docs
mkdir source/_static
make html

Publishing the docs online

If you have write permissions to pavics-sdi, you can also deploy the html online. To do so for the first time, create a new directory next to the pavics-sdi directory and clone the repo into an html directory:

mkdir pavics-sdi-docs
cd pavics-sdi-docs
git clone git@github.com:Ouranosinc/pavics-sdi.git html

Then enter html, checkout the gh-pages branch and enter some voodoo incantations:

cd html
git checkout gh-pages
git symbolic-ref HEAD refs/heads/gh-pages  # auto-switches branches to gh-pages
rm .git/index
git clean -fdx

You’ll also need to add a .nojekyll file to make sure the stylesheets are loaded on github.io:

git add .nojekyll
git commit -m 'added .nojekyll'
git push

You should then be able to go back to pavics-sdi/docs and run make gh-pages, which will build the html docs, copy them to the pavics-sdi-docs just created and push them to the github gh-branch:

make gh-pages

For more details, see the original instructions.

Translations

pavics-sdi is also being translated to French, and it’s possible to add other languages. For example to add a German translation, run sphinx-intl from the docs/ directory with the de locale:

sphinx-intl update -p build/locale -l de

This will create a locale/de/LC_MESSAGES folder storing .po files.

Translators will then be able to edit those .po files to translate the documentation content. Once that’s done, the documentation can be compiled using:

make -e SPHINXOPTS="-D language='de'" html

A make command to build the french documentation has been created to facilitate building:

make html_fr

When the source documentation in english changes and the translation needs to be updated, run:

sphinx-intl update -p build/locale

edit the .po files and rebuild the documentation.