Description
Takayuki Shimizukawa - Sphinx autodoc: automated API documentation [EuroPython 2015] [20 July 2015] [Bilbao, Euskadi, Spain]
Abstract:
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. In this session, I'll explain a documentation procedure that uses with sphinx autodoc and autosummary extensions.
Description:
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.
- make coverage; you can get the APIs that have not been documented.
- Write docstrings that includes the doctest format how to use the API.
- make doctest; you can verify each doctest part is correct or not.
- 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.
Target:
- Python programmer who is struggling with documentation.
- Python library author who want to generate API docs automatically.
- Python library author who want to create a clear documentation which contains python snippets.
Outline:
- Self introduction (2 min)
- Sphinx introduction (2 min)
- What is Sphinx?
- Sphinx examples
- Have you written API docs for your code? (2 min)
- I don't know what/where should I write.
- Docstrings is needed? Are there some specific format?
- Getting start Sphinx (2 min)
- How to install Sphinx
- How to start a Sphinx project
- Generate API docs from your python code (5 min)
- setup autodoc extension
- write docstrings for yuor python module
- "automodule & make html" will generate API docs from python code
- autodoc pros & cons: docs for many modules
- Listing APIs automatically (5 mins)
- setup autosummary extension
- how to use autosummary directive
- no more autodoc directive
- Discovering undocumented APIs (5 min)
- setup coverage extension
- make coverage
- Detect deviations of the impl and doc (5 min)
- setup doctest extension
- make doctest
- Overall picture, tips, Q&A (10 min)
- Overall picture of the process
- Options for autodoc
- translate them into other langs