ReadTheDocs documentation
Since many/most of the functions and classes in IW2D have a docstring written in the Sphinx format, it would be nice to actually use this to generate an online documentation. To do this using ReadTheDocs, these are in rough terms the steps that need to be taken:
- Initialize a sphinx documentation folder using
sphinx-quickstart
. Here is a guide for how to do it: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html - Add
.rst
(or.md
, with some extra setup required) files for any pages about the package as a whole, for instance a theory page or an installation page. - Much of the sphinx configuration can probably be copied from Neffint.
- In
conf.py
,sphinx.ext.autodoc
is needed to generate API reference from docstring, andnbsphinx
andnbsphinx_link
are needed to copy example notebooks into example pages in the documentation. - For example notebooks, a
.nblink
file must be added with the same name as the notebook, with a path to the notebook. The notebook should be run before it is saved (i.e. the output should already be generated). - In
setup.py
, the needed packages are added under the"docs"
key of the dependencies -
.readthedocs.yaml
is more or less taken exactly from the readthedocs template -
index.rst
shows how to actually include the pages in the project
- In
- The documentation can be generated locally with
sphinx-build -b html docs/source docs/build/html
. It may be needed to installpandoc
, for instance fromapt-get
(not pypi as it is very outdated) - Once the documentation generates fine locally, it can be uploaded to readthedocs, following their guide for starting a project: https://docs.readthedocs.io/en/stable/tutorial/index.html
- For production, the readthedocs documentation should of course target the
master
branch, but for testing before making an MR, it can be set to point to the documentation development branch
- For production, the readthedocs documentation should of course target the
- There will likely be some errors from reading invalid rst in the docstrings, so one should go over and fix those.
- In addition, some docstrings might not render as nicely as intended, so some syntax correction to make it look better is probably a good idea. Exchanging single backticks ` with double backticks ``, which applies code styling in rst, is probably a good idea.
- Also check that the docstrings make some sense in isolation
- Add
__all__
list to__init__.py
, as is done in Neffint.