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 is explained in detail on the website of the Japan Users Association. Of course, the installation procedure is also included.
In the above explanation, ʻeasy_install is used, but if you are using
pip install Sphinxor Anaconda / Miniconda, you can also install it with
conda install Sphinx`.
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.
requirements.txt
will be redundant.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.
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"]
sys.path.insert
around the 23rd line, put the path to the created Python package.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.
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