Generating documentation using Sphinx

A tutorial on automatic generation of documentation using Sphinx

Install sphinx using one of the following commands-

sudo apt-get install python-sphinx (python3-sphinx if you are using python3) 

sudo pip install sphinx (pip3 if you are using python3)  

If sphinx was already installed,update it using-

sudo pip install --upgrade sphinx (pip3 for python3)

Navigate to your project's root directory(cd project/).In your terminal, run this command to start the QuickStart for Sphinx which will help in generating the basic structure for your documentation-

sphinx-quickstart
Root path for the documentation [.]: docs  (This creates a project/docs which will contain your documentation)
Separate source and build directories (y/n) [n]: n (Entering 'n' will keep the source .rst source files directly in the docs directory)
Name prefix for templates and static dir [_]: (Press Enter for default configuration)  

Enter relevant details for the following-

Project name: 
Author name(s):
Project version []:  
Project release []:  

Leave out the following fields to their default configuration-

source file suffix
name of the master document
epub builder

Enabling autodoc-

autodoc: automatically insert docstrings from modules (y/n) [n]: y ('y' in the autodoc option which will be useful in generating automatic documentation from the code.  

Leave out the following fields to their default configuration-

doctests
intersphinx
to-do entries  

Enabling doc coverage-

coverage: checks for documentation coverage (y/n) [n]: y  

Leave out the following fields to their default configuration-

png maps
mathjax
ifconfig  

viewcode:If you want to include links to your code directly from your documentation,enter 'y' in the linking option
Enable makefile(for regeneration of docs)  

Your basic framework is now setup.

In project/docs/conf.py -uncomment imports of os and sys.
Uncomment and modify sys.path.insert(0, os.path.abspath('.')) such that it now points to the contents of your 'lib' which contains the code.
For example, for /project/lib ,the command will be as follows-

sys.path.insert(0, os.path.abspath('./../lib'))  

If you are using python3,open the docs/Makefile and replace the SPHINX-BUILD line by:

SPHINXBUILD   = python3 -c "import sys,sphinx;sys.exit(sphinx.main(sys.argv))"  

(Refer : https://stackoverflow.com/questions/8015225/how-to-force-sphinx-to-use-python-3-x-interpreter)

Ensure that a __init__.py exists in all modules for which auto-docs must be generated.
Now,to automatically generate the documentation for your modules,navigate to your docs directory and run-

sphinx-apidoc -o ./ ../lib/
                  ^    ^
                 dest  src  

Now,you have the rst files for your modules and they are linked in the modules.rst file.
To include it in the Table Of Contents(TOC),add a line namely 'modules' (and not modules.rst) in your index.rst
Create introduction .rst and other files according to your requirement and add them to your TOC. This tutorial will guide you in writing the rst files.
(Refer : https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html)

To generate html pages from your .rst files,run-

sudo make html  

The HTML pages are in _build/html and you can open the index.html to get your documentation.