◆SAMPLE◆ Sphinx autodoc: automated API documentation(en)
◆THIS IS SAMPLE DESCRIPTION◆ Using the automated documentation feature of Sphinx, you can make with ease the extensive documentation of Python program. You just write python function documents (docstrings), Sphinx organizes them into the document, can be converted to a variety of formats.
Get knowledge to generate documentation from source code automatically.
◆THIS IS SAMPLE ABSTRACT◆ Sphinx provides autodoc feature that generate document from docstring in your python sources. The docstring that contains description and example of the use of function written near the program, makes doc easy to update. In addition, the output of the Sphinx will make you understand what to write in docstring. As a result, this will improve your motivation of doc writing. To use the autodoc, you must specify python modules to automodule directive one by one. This is a tedious task, hoswever autosummary extension automate this task. In most cases, once developers have developed the API, you only need to run the make html of Sphinx, you get a nicely formatted document. Sphinx also has coverage and doctest extentions. These support writing the documentation to work with autodoc. This allow you to check the APIs that have not been documented or you can verify each doctest part is correct or not. If you use such autodoc-related extensions, you can create a Sphinx API documentation in the following procedure. 1. make coverage; you can get the APIs that have not been documented. 2. Write docstrings that includes the doctest format how to use the API. 3. make doctest; you can verify each doctest part is correct or not. 4. make html; you can generate the HTML or your favorite format. In this session, I'll explain a documentation procedure that uses with sphinx autodoc, autosummary, coverage and doctest extensions.