Publish Python Project Documentation on Confluence/HTML using Sphinx

The code documentation is essential in every project. Code documentation can be split into multiple parts. The first one is comment blocks, most helpful for programmers; These will be found through every file explaining classes, methods, parameters, possible errors. Then comes the file documentations. These are usually generated through a script that will parse a file and, based on the description in the docstrings, will create an explicit PDF. Afterwards, there should be information about the location of the code repository; additionally, there should be detailed instructions on how to run the project.

In this article, We will look into the file documentation which is generated by Sphinx. This documentation generator can be used to create .pdf, .HTML or publish the technical documentation page to a Confluence instance.

Why Confluence for technical documentation?

Confluence is a great place to create, collaborate, and organize all your work in one place.

1. Can Be Used Company-Wide
2. Allows You to Engage Colleagues and Readers
3. Web-Based, No need to download any software
4. Ideal for Agile Environments

Create a confluence account and create a space where you want to store the documentation

Getting started with Sphinx

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of multiple reStructuredText sources), written by Georg Brandl. It was originally created for the new Python documentation and has excellent facilities for Python project documentation, but C/C++ is supported as well, and more languages are planned.

Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.

The steps involved in creating the documentation;

GitHub code

1. Go to the root directory of the python project. In the case of a small project go to the directory which contains all the .py files
2. Create a Python 3 virtual environment. In my case, venv is the name of the virtual environment

Open the cmd; shift + right click and open command window here

virtualenv -p python3 venv

3. Activate the virtual environment.

cd venv/Scripts
activate.bat

Make sure you are in the virtual environment throughout the project

4. Install all the project requirements

pip install -r requirements.txt
OR
pip install Sphinx
pip install rinohtype
# The recommended method of installation is using pip for confluence
pip install sphinxcontrib-confluencebuilder

Sphinx and Rinohtype are already inside the requirements.txt file.

5. Create a docs directory and cd into this directory. This is where all the files of documentation will be present.

mkdir docs
cd docs

6. Setup Sphinx

sphinx-quickstart

Initial configuration

Docstring format for Sphinx documentation;

Docstring format

7. Open source/conf.py

• Configure the path to the root directory

Uncomment lines 15–17 and paste the following code

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

The path should point to the root directory of the project and looking at the project structure, from conf.py we should reach the root by going up two parent directories.

Main Directory

• Add these extensions in the conf.py

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'sphinxcontrib.confluencebuilder'
]
# 'sphinxcontrib.confluencebuilder' is for confluence

• Add latex elements in the conf.py

latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
    'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
    'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
    'preamble': '',
# Latex figure (float) alignment
    'figure_align': 'htbp',
}

• Include a series of publish-related settings to the configuration file: (*optional, only if you want to publish in confluence)

confluence_publish = True
confluence_space_name = 'TEST'
# (for confluence cloud)
confluence_server_url = 'https://example.atlassian.net/wiki/'
confluence_server_user = 'myawesomeuser@example.com'
confluence_server_pass = 'myapikey'
# (or for confluence server)
confluence_server_url = 'https://intranet-wiki.example.com/'
confluence_server_user = 'myawesomeuser'
confluence_server_pass = 'mypassword'

For example:

confluence_publish = True
confluence_space_name = 'SPEC'
# (for confluence cloud)
confluence_server_url = 'https://spectrra.atlassian.net/wiki/'
confluence_server_user = 'email@gmail.com'
confluence_server_pass = 'jhfgjsdfjhasdjfg'

How to get the confluence_server_pass for your project: Get API Key

For detailed installation: Atlassian Confluence Builder for Sphinx

8. Open the index.rst and change the content to the following. (Click the index.rst link for full content)

Documentation for the Code
**************************
.. toctree::
   :maxdepth: 2
   :caption: Contents:
codename1
===================
.. automodule:: codename1
   :members:
codename2
=====================
.. automodule:: codename2
   :members:
# In case of many modules;
main
===================
.. automodule:: app
   :members:
controller
=====================
.. automodule:: main.controller
   :members:
models
=================
.. automodule:: main.models
   :members:

9. Create the documentation files.

Type the commands in the docs directory

• Create HTML

make html

Building the pdf file would fail if your Python version is ≥3.7.0 (Github issue reference)

Snapshot of the HTML page;

Snapshot of the documentation; index.html

Snapshot of the documentation; index.html

This would produce the HTML file in docs/build/html/index.html

• Publish on confluence

make confluence

NOTE: Run make clean before make confluence, If the confluence fails to load.

IMP: You can export the confluence page as PDF

Export to PDF from Confluence page

Snapshot of the confluence page;

Snapshot of the confluence page

Once everything is setup; If you make any changes in the documentation of the code, Then open cmd and run the following;

Commands

To learn more please refer to the following links;

• Writing docstrings: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html and https://pythonhosted.org/an_example_pypi_project/sphinx.html
• Sphinx: https://www.sphinx-doc.org/en/master/index.html
• Atlassian Confluence Builder for Sphinx: https://sphinxcontrib-confluencebuilder.readthedocs.io/en/latest/index.html
• Link to the GitHub repo: https://github.com/Shravankumarhiregoudar/sphinxDocumentation

Thanks for your time. I hope this article helped you.