Automatically create python documentation

This is a memo about the procedure for automatically creating a python document using sphinx. For the time being, please forgive me because it is a summary in the situation of "moving". sphinx can automatically convert comments written in python code to html. This time, we will try to automate the document with a configuration that links and lists the source code of multiple directories as shown below on a common top page.

 - dirA
    - test.py
    - test2.py
 - dirB
    - testB.py
 - docs

Initially, docs is empty because it is the directory where the automatically generated documents will be stored. Execution environment: Ubuntu18.04 Python：3.6

0. Preparation of Python program

Each python code prepared for the experiment has a comment in the source code as shown below. If you write a comment in the notation docstring, the description will be automatically added to the HTML file when using sphinx. Add one of the docstrings, Google Style, etc. as appropriate. https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

class test():
    """test Class
    """
    
    def __init__(self):
        self.val = 0
    
    def SetVal(self, val):
       """SetVal function
       """
       self.val=val

    def GetVal(self):
        """GetVal function
        """
        return self.val

1. Install sphinx

$ sudo apt install python3-sphinx

2. Generate sample Makefile

2.1 Run sphinx-quickstart

The sphinx-quickstart command will generate a set of Makefiles for building html files in the specified directory. When you execute the command, you will be asked to enter questions and answers interactively. This time, set only the following, and execute the rest by default.

$sphinx-quickstart docs
...
ProjectName: sphinxTest
Auther name: hoge
Language: ja

After executing the above, some files and directories will be created under docs. Then edit the generated file for the environment in which you are generating the document.

2.2 Editing conf.py

Near line 20 The relative positional relationship between the directory containing the sample Makefile and the directory where the target python code group is confirmed is specified here.

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

Near line 35 This is an option for automatic document generation. For more information http://www.sphinx-doc.org/ja/1.2/extensions.html

extensions = ["sphinx.ext.autodoc","sphinx.ext.autosummary"]

Near line 98 Change the design of the HTML page. (Any)

html_theme = 'default'

3. Automatically generate Sphinx compatible documents

3.1 Run sphinx-apidoc

Execute the following command to automatically generate the code document that exists in the two directories.

$ sphinx-apidoc -f -o docs/dirA ./dirA
$ sphinx-apidoc -f -o docs/dirB ./dirB

After executing the above command, under docs dirA / modules.rst, test.rst, test2.srt are generated. Each file is written in a format called reStructeredText. See below for details. https://www.sphinx-doc.org/ja/master/usage/restructuredtext/basics.html modules.rst is a file that is automatically generated when shinx-apidoc is executed. A list of files existing under the target directory is automatically generated. For example, this time the description is as follows.

dirA
====

.. toctree::
   :maxdepth: 4

   test
   test2

It means that modules.rst has a tree structure that refers to test.rst and test2.rst.

3.2 Editing index.rst

When you run sphinx-quickstart, a file called ./docs/index.rst is generated. Use this as the top page of the html file. If you refer to the modules of each directory from index.rst, the files in each directory will be automatically added to the html document. So, modify ./docs/index.rst.

Welcome to test's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   ./dirA/modules
   ./dirB/modules
<Omitted below>

4. Build the html file

Finally build the html file

$ sphinx-build -b html ./docs ./docs/_build/

This will automatically generate an html file under _build. Double-click on ./docs/_build/index.html The file created this time will appear as shown below.

that's all. Thank you for your hard work.

Try to automatically generate Python documents with Sphinx