Creating Python API documentation with Sphinx

It is convenient if you can see the API document of the class you are making while making a program So, I summarized how to automatically create and browse API documents for Python modules using Sphinx.

environment

Linux (I did it on CentOS 6.6 this time) Python 2.7 (with pip installed)

Put Sphinx

Sphinx is a document creation tool. (By the way, it's written in Python.) In short, it's a tool that makes it easy to create "intelligent and beautiful documents." Reference: http://docs.sphinx-users.jp/

With pip, it's easy to install.

$ pip install sphinx

Prepare to automatically generate API documentation

I did it with the following directory structure.

- project #Python project
   |
   |- src #A directory of Python code for which you want to automatically generate API documentation
   |   |- __init__.py or something
   |   |- hoge #Submodules
   |
   |- docs #Sphinx project directory

Create a Sphinx project for your API documentation in the docs directory. This can be created with a single command.

$ cd project
$ sphinx-apidoc -F -o docs/ src/

In the "-o" option of the sphinx-apidoc command, specify the directory where you want to create the Sphinx project, and in the last argument, specify the directory of the Python source where you want to generate the API document. (The "-F" option seems to be an option to create a full-featured Sphinx project. I'll add it for now.)

Now you are ready to generate the API documentation from the Python source under the src directory. (Early

Create an API document from your own Python source.

Go into the docs directory and run the make command.

$ cd docs
$ make html

This will create an API document from your Python source.

If you write a comment in dot stiring, it will be reflected as well.

By the way, if you update the source code Do "make html" again to get the latest API documentation.

View API documentation

docs/_build/html An HTML file is created under it. "Index.html" is the home page.

If you can see it locally, open it in your browser.

There is no GUI on the remote VM! Who says

$ cd _build/html
$ python -m SimpleHTTPServer

So, if you set up a simple web server, you can see it remotely. It's just simple and there seems to be no cache, so HTML file update (make html) → browser update (F5) You can see the latest information at.

reference

I found it in the middle of writing.

http://qiita.com/icoxfog417/items/9e2eb932b61aa9b9e427

If you want to know more details, please see ↑.

Automatically create Python API documentation with Sphinx