We all know that programmers write code but many of us are not aware that they read more than write. The clean code will be easier to read. In this article, I am going to explain about the process of writing and publishing the python code documentation easy and effective way. Below is the table of content,
Good programmers prefer to write the logic behind each class, methods, function etc using comments. In python, the best way to add the comments for the functions or class is to write in docstring format. Later, it can be used by documentation automation tools like sphnix to generate the document. But for the automation, you should follow the standard docstring guideline. Here is the small example of good docstring example,
def add(x, y): """Function to add two numbers Parameters ---------- x: int First number to add y: int Second number to add Returns ------- int The sum of x and y """ return x + y
Now next step is to install the sphnix. It can be installed easily using
pip install sphinx
In the root directory of your project, run
sphinx-quickstart to initialize the sphinx source directory to create a default configuration. I prefer to have separated directory for
source, I hope you will also do the same.
Below image is the example of my
As shown above, running the sphinx-build command creates a
make.bat file, as well as
conf.py file is inside the
source folder which describes the sphinx configurations to control the documentation. Here, I recommend you to overwrite the following things,
In the project information section, you need to update about
release etc. Following is the example of my project information,
# -- Project information ----------------------------------------------------- project = 'GeoTile' copyright = '2022, Tek Kshetri' author = 'Tek Kshetri' # The full version, including alpha/beta/rc tags release = '0.1.0'
By default, there will be no extension added to the documentation. You have to add at least following extension to generate the documentation
extensions = [ 'sphinx.ext.doctest', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon', ]
The default theme for sphinx is alabaster. There are several other themes are available, but personally, I like
pydata_sphinx_theme. To change the theme, you need to install it first using terminal,
pip install pydata_sphinx_theme
And update it to the
# html theme for documentation html_theme = "pydata_sphinx_theme"
There are several ways to customize this theme. If you are interested, please check the official documentation of
At the top of the
conf.py file, you will see some commented line of code. If your python code path is outside the documentation directory (Most of the case is like this), you have to specify the path to the code like below,
import os import sys sys.path.insert(0, os.path.abspath('../..'))
Here is my folder structure,
Sphinx generates the HTML documentation from reStructuredText (rst) files. To autogenerate the rst files, run the sphinx-apidoc command using following syntax:
sphinx-apidoc -o <OUTPUT_PATH> <MODULE_PATH>
In my case, the output directory is
source, and the module directory is
testCode. I have to run following command from documentation root folder,
sphinx-apidoc -f -o source ../testCode
The above command will create at least two files,
test.rst. You can open it with any text editor and see the configuration or manually edit the things as well.
Before building the HTML document, we need to insert the
modules.rst file to
toctree. Please add the
API reference <modules> to
toctree as below,
.. toctree:: :maxdepth: 2 :caption: Test Documentation API reference <modules>
After that run the following command from your documentation root directory,
This command will generate the
html file inside the
build directory. You can open it with any browser to check the documentation.
To publish the documentation, I am going to use Read the Docs open-source solution. Using
read the docs, you can publish your documentation free of cost. Here is the guideline for publishing,
If you don't have
read the docs account, create account and login to the read the docs site.
In your user dashboard, there is option to Import a Project. Click the option, again click on Import Manually button. Add the project name, repository URL (GitHub url to your documentation), and default branch and click next.
Again add the extra details about your project.
The final step is to build the version and view the docs,
If you did everything correctly, live version of your documentation will be rendered after clicking view docs button.
I hope this blog post is informative for you. If you like this blog, please support me by subscribing to my YouTube channel: https://www.youtube.com/c/iamtekson