Create Python project documentation in Sphinx

Sphinx has become a major tool for writing documentation in Python projects, such as Sphinx. Therefore, here we will explain the procedure for creating a Python project document in Sphinx.

Sphinx installation

Sphinx is explained in detail on the website of the Japan Users Association. Of course, the installation procedure is also included.

Sphinx-Users.jp

In the above explanation, ʻeasy_install is used, but if you are using pip install Sphinxor Anaconda / Miniconda, you can also install it withconda install Sphinx`.

As of August 2, 2015, Babel's latest version 2.0, which Sphinx depends on, has a [problem] in the Python3 environment (https://github.com/mitsuhiko/babel/issues/174). To work around this, run pip uninstall babel and then downgrade with pip install babel == 1.3, but install directly from the branch on GitHub (pip install git + https: //github.com/mitsuhiko/[email protected]).

Since Sphinx is a tool that is used in common with projects, I think it is better to install it globally, not in a virtual environment such as virtualenv.

If you install it in the virtual environment, the dependent library of the project itself and the dependent library of Sphinx just for creating documents will be mixed, and requirements.txt will be redundant.

Document creation

From here, we will actually create the document. I think that it is easier to get an image if there is a concrete example, so I prepared a sample repository below. I think it is easier to understand if you refer to here for the folder structure and the modified parts of the source.

icoxfog417/python_doc_sample

First, create a folder called docs directly under the Python project and create documents there. Go to the docs folder you created and run sphinx-quickstart to create a template.

sphinx-quickstart

For more information on this command, see "Detailed description of sphinx-quickstart" on this page (http://sphinx-users.jp/gettingstarted/make_project.html).

The document is now ready. However, something like an API reference naturally wants to be automatically generated from the source code. In Sphinx, you can use sphinx-apidoc to generate documents from this source code. The following command generates the document of the Python package python_doc_sample in ʻapis in the docs` folder (command is executed from the root of the project).

sphinx-apidoc -f -o docs/apis python_doc_sample

Note that depending on the import method, even the imported document will be created in the form of a potato (see here](http://shouhei.github.io/blog/2014/12/29/shpinxdeapifalsedokiyumentosheng-cheng-wosurushi) -falsezhu-yi-dian /)).

You now have the documentation and API reference for your project. In both cases, the document is written in the reStructuredText format with the extension .rst. Eventually, you need to convert this to HTML format. The command for that is sphinx-build, but it's easier to use make (even on Windows, it's available because make.bat is created when you run sphinx-quickstart).

make html

And, edit conf.py before executing the command (it should be directly under the docs folder). This is because automatic documentation from Python code is not turned on by default.

`conf.py`


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

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

In sys.path.insert around the 23rd line, put the path to the created Python package.
Add the extension sphinx.ext.autodoc to create API documentation in ʻextensions` around line 33.

If you execute make html after modifying conf.py, an HTML file will be created in the _build folder, and you can refer to the following web page.

And from the Module Index link, you can search / reference the API document created from the package in the project.

If you write the comments properly, it will look like the following.

After that, after updating the document (.rst), the HTML page will be updated with make html. However, if you want to modify the source code, you need to execute sphinx-apidoc, and if this is troublesome, you can make a simple batch or script (Sample. com / icoxfog417 / python_doc_sample / blob / master / make_docs.py)).

The commands introduced above are referenced below, so please refer to them when checking the meaning of options.

Sphinx Documentation

Publishing the document

Since the created document is an HTML page, you can easily publish it on the server. For GitHub repositories, you can use GitHub pages.

Creating Project Pages manually

Push the _build folder where the HTML page is created to gh-pages and the publication is complete. However, please note that you need a .nojekyll file to access static files.

You can now create and publish Python project documentation in Sphinx!