Common issues/bugs found using the sphinx documentation tool

Note

I am actively working on more FAQs. Stay tuned!

The file structure of this mini project is the following:

.
├── Makefile
├── build
│   ├── doctrees
│   │   ├── <content-omitted>
│   └── html
│       ├── _sources
│       ├── _static
│       ├── genindex.html
│       ├── index.html
│       ├── libs-rst-files
│       ├── objects.inv
│       ├── py-modindex.html
│       ├── readme_dir
│       ├── search.html
│       └── searchindex.js
├── libs
│   ├── __init__.py
│   └── my_module.py
├── make.bat
└── source
    ├── conf.py
    ├── index.rst
    ├── libs-rst-files
    │   ├── libs.rst
    │   ├── modules.rst
    │   └── my_module.rst
    └── readme_dir
        └── index.rst

One common issue is sphinx not able to pick up the documentation for the modules in the libs directory. This is because the libs directory is not in the sys.path of the python interpreter.

To fix this, we need to add the following lines to the conf.py file:
```
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('../libs'))
```
Note

The path you provided must be relative to where the conf.py is located. In this case, conf.py is located in the source directory, so we need to go up one level to reach the root directory of this mini project.
Make sure sphinxcontrib.autodoc_pydantic is added as part of the extensions list.
```
extensions = ['sphinxcontrib.autodoc_pydantic']
```
Generate autodoc
```
# suppose you are in the root directory of this mini project
$ sphinx-apidoc -o source/libs-rst-files/ ../libs
```
This will generate libs-rst-files directory inside source. All the rst files inside are auto-generated by sphinx.
In source/index.rst, make sure libs-rst-files/modules.rst is added.
Go to root directory of this mini project and run make html. Then html files will be generated inside build/html/ directory.