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`.

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.

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

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"]

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.

image

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

image

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

image

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!

Recommended Posts

Create Python project documentation in Sphinx
Write documentation in Sphinx with Python Livereload
Automatically create Python API documentation with Sphinx
Create SpatiaLite in Python
Create a function in Python
Create a dictionary in Python
Create gif video in Python
[Note] Project Euler in Python (Problem 1-22)
Functional programming in Python Project Euler 3
Create a DI Container in Python
Project Euler # 5 "Minimum Multiples" in Python
Create a binary file in Python
Create Gmail in Python without API
Automatically build Python documentation with Sphinx
Create a Kubernetes Operator in Python
Functional programming in Python Project Euler 2
Project Euler # 15 "Lattice Path" in Python
Create a random string in Python
Project Euler # 4 "Maximum Palindrome" in Python
Create and read messagepacks in Python
Create your own Linux commands in Python
Project Euler # 3 "Maximum Prime Factors" in Python
Create a new Python numerical calculation project
Project Euler # 11 "Maximum Product in Grid" in Python
Create ScriptableObject in Python when building ADX2
[LLDB] Create your own command in Python
Create a simple GUI app in Python
Create a JSON object mapper in Python
Create Qt designer parts in Python (PyQt)
Project Euler # 7 "1000 1st prime number" in Python
Project Euler # 16 "Sum of Powers" in Python
Project Euler # 9 "Special Pythagorean Triple" in Python
[GPS] Create a kml file in Python
Project Euler # 14 "Longest Collatz Sequence" in Python
Project Euler # 2 "Even Fibonacci Numbers" in Python
Project Euler # 17 "Number of Characters" in Python
Project Euler # 1 "Multiples of 3 and 5" in Python
Quadtree in Python --2
Python in optimization
CURL in python
Metaprogramming in Python
Python 3.3 in Anaconda
SendKeys in Python
Epoch in Python
Discord in Python
Sudoku in Python
DCI in Python
quicksort in python
nCr in python
N-Gram in Python
Programming in python
Constant in python
Lifegame in Python.
FizzBuzz in Python
Sqlite in python
StepAIC in Python
N-gram in python
LINE-Bot [0] in Python
Csv in python
Disassemble in Python
Reflection in Python