[PYTHON] Getting started with Sphinx. Generate docstring with Sphinx
Automatically generate python docstring with Sphinx-apidoc Uses OSX 10.9.4. Use Sphinx v1.1.3. After installing sphinx. What do you do now?
Directory structure
├── documents_source/
├── publish/
└── src/
└── main.py
main.py
# -*- coding: UTF-8 -*-
import sys
def main(name, age=None):
"""Greeting function.
:param name: Your name.
:param age: Youre age. (option)
"""
print "hello, " + name
if age is not None:
print "You are " + age
Document stationery generation
Execute the sphinx-apidoc command.
$ sphinx-apidoc -F -o ./documents_source ./src
The above is only for the first time. Generate a complete configuration with the -F option. From the second time onward, execute this.
$ sphinx-apidoc -f -o ./documents_source ./src
There are many files under `` documents_source / ``. This is the source of the generated document.
## Allow the target module to be imported
Open `` documents_source / conf.py`` and edit and enable this commented out part. The autodoc module imports and reads the target file, so it tells you the location.
#### **` conf.py`**
```py
#sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../src'))
Document output
Execute the sphinx-build command.
$ sphinx-build -a ./documents_source ./publish
Check that it will be output as a document that can be viewed under the publish / directory.
It is displayed as follows.
It is easier to understand if you read the official document after suppressing this flow. http://docs.sphinx-users.jp/index.html
Recommended Posts