-
Notifications
You must be signed in to change notification settings - Fork 83
Documentation
We use "Read the docs" for documentation building and hosting. Documentation is generated using Sphinx. The latest documentation is available at https://tia-toolbox.readthedocs.io/en/latest/.
Sphinx is the tool used to generate the documentation for Read the Docs. Sphinx takes restructed text files (similar to markdown) and converts them to themed web based documentation.
https://www.sphinx-doc.org/en/stable/usage/quickstart.html
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
We use the autodoc extension for Sphinx. This allow for the conversion of docstrings into documentation entries automatically.
This section is copied from the autodoc page linked above. It is important to note that the files get imported when generating documentation.
autodoc imports the modules to be documented. If any modules have side effects on import, these will be executed by autodoc when sphinx-build is run.
If you document scripts (as opposed to library modules), make sure their main routine is protected by a if __name__ == '__main__' condition.
We use the napoleon extension for Sphinx. This allows for the use of Google form docstrings. The extension automatically converts these to restructured text that Sphinx can parse.
It is possible to use markdown instead of restructured text. Currently this is not enabled.
For more see:
There are some notable disadvantages to using markdown however. One is that you cannot include another file in markdown as you can so with restructured (rst) files. However, an rst file can include a markdown file.
This kind of functional command which can be included in rst files is called a directive. See the Sphinx QuickStart and the reStructured Text Primer for more on this.
Sphinx can also output documentation as a LaTeX rendered PDF document, provided that LaTeX is installed.
See the sphinx-build page for more:
https://www.sphinx-doc.org/en/master/man/sphinx-build.html
Please use MLA (First on Google Scholar) for citation style