GitLab

These are general notes on the styling of the project and things we need to be careful.

Make sure to install sphinx and sphinx-rtd-theme first:

pip install sphinx
pip install sphinx-rtd-theme

To build the documentation make sure to first run pytest as this will generate the imgs in the tmp folder for sphinx.

pytest --doctest-modules ketos/

Then, from the docs folder run make html

cd docs/
make html

1. We are using the Read the docs (rtd - https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html) styling for sphinx. I have altered a little bit of the layout.html of the original rtd theme to allow for 2 logos to be inserted as well as to allow for a link to the meridian website. You can find this layout in the _templates folder.

2. In order to generate a single docs page for each function and or class of a sub-module, we need to use the autosummary extension of sphinx. Autosummary will generate a table with every method and class within the submodule. In order for sphinx to auto-generate an rst page for each one of these functions and classes, you need to set autosummary_generate = True in the conf.py file. All these rst files will be generated in a folder called 'generated' which is included in .gitignore and should not be pushed to the repository. I had to slightly alter the sphinx autosummary templates for class.rst and base.rst to achieve what I wanted. You can find these templates in the _templates/autosummary folder.

3. For the user, autosummary is great as you can easily see the methods and classes and jump between them. Before, automodule was being used alone and it would generate a single page for an entire submodule making it hard to find anything. However for us the developers it will make future documentation harder as we need to manually write the name of the new function or class in order for autosummary to detect it. There is an optional parameter called :recursive: that we could add to the autossumary that in theory would travel through the entire project structure and create a stub page for everything without us having to manually insert anything. In fact, in theory, we would only need the root index.rst folder and autossumary would find all the functions nad classes in all submodules automatically. I couldnt get this to work, but if anyone wants to spend some time with it: https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html

4. We should be careful with imported docstrings from overridden methods from other modules. For instance all our NN have a method called call(). this is a method that we override from tf.keras.Model and we didnt have any docstring for it. What sphinx does is it will use instead the original docs from tensorflow, which have a different styling from ours, and thus breaking the styling. I had to manually copy the docs from tensorflow and add it as a docstring with the proper formatting. Sphinx should give an error when this happens though.