Generate Documentation

Documentation is the best and the most important part of any development process.

We use sphinx for generating documentation from docstrings of our python code. Our developers believe in the value of documenting their code and recommends everyone to do that.

1. Go to the project directory 'atarashi'.

2. Install Sphinx and m2r

   pip install sphinx m2r

Since this project is based on python so pip is already installed.

3. Initialise docs/ directory with sphinx-quickstart

   mkdir docs
   cd docs/
   sphinx-quickstart
   

• Root path for the documentation [.]: .

• Separate source and build directories (y/n) [n]: n

• autodoc: automatically insert docstrings from modules (y/n) [n]: y

• intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y

Else use the default option

4. Setup the conf.py and include README.md

• Enable the following lines and change the insert path in conf.py

Open source/conf.py and uncomment these lines:

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

The path should point to the root directory of the project.

• Enable m2r to insert .md files in Sphinx documentation

In your conf.py file, add the following lines:

[...]
extensions = [
  ...
  'm2r',
]
[...]
source_suffix = ['.rst', '.md']

When m2r extension is enabled on sphinx and .md file is loaded, m2r converts to rst and pass to sphinx, not making new .rst file.

• Include README.md by editing index.rst

.. toctree::
    [...]
    readme
.. mdinclude:: ../README.md

5. Auto-generate the .rst files in docs/source which will be used to generate documentation

cd docs/
sphinx-apidoc -o source/ ../atarashi

6. cd docs
7. make html

This will generate file in docs/_build/html. Go to: index.html You can change the theme of the documentation by changing html_theme in config.py file in docs/ folder. You can choose from {'alabaster', 'classic', 'sphinxdoc', 'scrolls', 'agogo', 'traditional', 'nature', 'haiku', 'pyramid', 'bizstyle'} Reference