How to generate automatic docs - gecos-lab/PZero GitHub Wiki

Sphinx is a tool for generating automatic documentation, it uses the reStructuredText markup language by default, and can read MyST markdown via third-party extensions. Both of these are powerful and straightforward to use and have functionality for complex documentation and publishing workflows. They both build upon Docutils to parse and write documents.

Notes:

If you have already installed on your OS sphinx and sphinx_rtd_theme, and already downloaded PZero from GitHub, you can skip the Installation and Configuration steps, and go directly here to the generation step!

Installation from scratch:

Install sphinx and sphinx_rtd_theme with conda (or pip):
```
 conda install sphinx sphinx_rtd_theme
```
Create 'docs' folder:
```
 mkdir docs
```
Enter the docs folder and run sphinx-quickstart:
```
 cd docs
 sphinx-quickstart
```

Configuration from scratch:

Edit "conf.py" file:
- Uncomment these lines
```
 import os
 import sys
 sys.path.insert(0, os.path.abspath('.'))
```
- Change the last line from sys.path.insert(0, os.path.abspath('.')) to sys.path.insert(0, os.path.abspath('..')) (this is needed for setting the parent folder as a sphinx source folder)
- Add these extensions or more (those are optional except for the first one):
```
 extensions = [
		 'sphinx.ext.autodoc',
		 'sphinx.ext.viewcode',
		 'sphinx.ext.napoleon'
	 ]	
```
- Change html theme (optional):
```
html_theme = 'sphinx_rtd_theme'
```
Return in the 'PZero' folder and create auto-doc for 'pzero' folder:
```
 cd ..
 sphinx-apidoc -o . ../pzero
```
Add 'modules' inside "index.rst" after the line :caption: Contents::
```
.. toctree::
:maxdepth: 2
:caption: Contents:

modules
```

Generate automatic documentation:

To generate HTML pages with documentation run the following command inside the 'docs' folder (make clean html needs to be used only when you want to recreate the docs/it deletes the ):
```
make clean html
make html
```
Now you can open and run 'index.html' inside 'docs/_build/html' folder to see the generated docs!

Troubleshooting:

Error Unexpected indentation: You can solve this issue by adding one new line after the first line of the comment title inside a function. Also the comment with """ must be in the first and in the last written line.

From this kind of comment:

"""
Generic widget for input of several variables.
It takes as input:
"""

To this one:

""" Generic widget for input of several variables.

It takes as input:"""