Building the docs

This documentation is generated by sphinx, both from the source code and with some additional documentation files. To build it, you need a working dissemin install where you have installed the packages in requirements-dev.txt.

There are two steps to generate the docs: first, auto-generate the reStructuredText sources of the docs with sphinx-apidoc:

# first, make sure you are in an environment where
# the requirements are available
source .virtualenv/bin/activate
# then, invoke sphinx-apidoc via make
make -B doc

Then, compile these RST sources to HTML:

cd doc/sphinx ; make html

The HTML output is then available in doc/sphinx/_build/html/.

Generating model diagrams

The UML diagrams for the models are generated using the django-extensions library. When making changes to the models, these diagrams should be updated. They are generated as follows:

./manage.py graph_models papers | dot -Tpng -o papers_models.png

It is possible to generate a single graph for multiple apps, using:

./manage.py graph_models papers publishers deposit | dot -Tpng many_models.png

This relies on the graphviz package to render the graphs to PNG (apt-get install graphviz). More documentation about this feature can be found at https://django-extensions.readthedocs.io/en/latest/graph_models.html.