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,
1. Write the standard docstring
2. Install Sphinx
3. Initialize Sphinx
4. Update the conf.py
file
5. Auto generate the rst
file
6. Build HTML
7. Publish the documentation online
8. Reference
1. Write the standard docstring
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
2. Install sphinx
Now next step is to install the sphnix. It can be installed easily using pip
command,
pip install sphinx
3. Initialize the 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 build
and source
, I hope you will also do the same.
sphinx-quickstart
Below image is the example of my sphinx-quickstart
,
As shown above, running the sphinx-build command creates a Makefile
, a make.bat
file, as well as build
and source
directories.
4. Update the conf.py
file
The 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,
Add project information
In the project information section, you need to update about copyright
, author
, 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'
Add extensions
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',
]
Update theme
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 conf.py
file,
# 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 pydata_sphinx_theme
Specify the location of the python modules
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,
5. Auto generate the rst
file
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, modules.rst
and test.rst
. You can open it with any text editor and see the configuration or manually edit the things as well.
6. Build HTML
Before building the HTML document, we need to insert the modules.rst
file to source/index.rst
file 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,
make html
This command will generate the html
file inside the build
directory. You can open it with any browser to check the documentation.
7. Publish the documentation online
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,
Create account
If you don't have read the docs
account, create account and login to the read the docs site.
Import project
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
Top comments (0)