================= 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 :file:`pavics-sdi` directory and clone the repo into an :file:`html` directory:: mkdir pavics-sdi-docs cd pavics-sdi-docs git clone git@github.com:Ouranosinc/pavics-sdi.git html Then enter :file:`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 :file:`.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 :file:`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 :file:`docs/` directory with the ``de`` locale:: sphinx-intl update -p build/locale -l de This will create a :file:`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. .. _pavics-sdi: https://github.com/Ouranosinc/pavics-sdi.git