Common issues/bugs found using the sphinx documentation tool
============================================================

.. note::

   I am actively working on more FAQs. Stay tuned!

0. The file structure of this mini project is the following:

.. code-block:: bash

    .
    ├── 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

1. 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:

   .. code-block:: python

      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.

2. Make sure ``sphinxcontrib.autodoc_pydantic`` is added as part of the ``extensions`` list.

   .. code-block:: python

      extensions = ['sphinxcontrib.autodoc_pydantic']

3. Generate autodoc

   .. code-block:: bash

      # 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.

4. In ``source/index.rst``, make sure ``libs-rst-files/modules.rst`` is added.

5. Go to root directory of this mini project and run ``make html``. Then html files will be generated
   inside ``build/html/`` directory.