Python Doc Generation with Sphinx

Generated Documentation

Activity Outline

Prerequisite

$ . venv/bin/activate
$ pip install sphinx
$ pip install sphinx_rtd_theme

Initialising Docs

$ . venv/bin/activate
$ mkdir docs
$ cd docs
$ sphinx-quickstart # queries on basic setup shall starts
import os
import sys
sys.path.insert(0, os.path.abspath('../../'))
# this conf.py is in ./docs/source/conf.py
# therefore our source code is up 2 level then the directory of python source code is the i.e. ./python_dev_setup
html_theme = 'sphinx_rtd_theme'
Python Dev Environment in VSCode
====================================================================
.. toctree::
:maxdepth: 2
:caption: Readme
readme.. toctree::
:maxdepth: 2
:caption: Docstring
docstring/modules.. toctree::
:maxdepth: 2
:caption: Index
indices
$ vi docs/source/readme.rst
.. include:: ../../README.rst
$ vi docs/source/indices.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Build the Docs

$ . venv/bin/activate
$ rm -Rf docs/build
$ rm -Rf docs/source/docstring
$ sphinx-apidoc -f -o docs/source/docstring/ python_dev_setup # this is the steps where the docstring/modules going to be filled with our code docstring
$ cd docs && make html && cd ..
#!/usr/bin/env bashSOURCE_CODE_PATH=$1. venv/bin/activate
rm -Rf docs/build
rm -Rf docs/source/docstring
sphinx-apidoc -f -o docs/source/docstring/ $SOURCE_CODE_PATH
cd docs && make html && cd ..
$ . tools/build-doc.sh python_dev_setup

Conclusion

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store