I have a python file with functions (lib.py), without classes. Each function has the following style:
def fnc1(a,b,c):
'''
This fonction does something.
:param a: lalala
:type a: str
:param b: hahaha
:type b: int
:param c: hohoho
:type c: int
:rtype: int
'''
print a
d = b + c
return d
I just want to document each function (inputs and outputs) with Sphinx.
After doing sphinx-quickstart, I defined the path in conf.py with my lib.py. But the output HTML file (welcome page) is empty.
If I write myself in index.rst:
.. function:: func1(a,b,c)
This fonction does something.
:param a: lalala
:type a: str
:param b: hahaha
:type b: int
:param c: hohoho
:type c: int
:rtype: int
it is ok, it shows the inputs and outputs in html file. But how to do it automatically?
Normally, I think, it must to do it in lib.rst after doing sphinx-apidoc -o, but in lib.rst there is only:
lib module
==================
.. automodule:: lib
:members:
:undoc-members:
:show-inheritance:
Can somebody explain me step by step what I must do exactly?
First, when you run sphinx-quickstart, be sure you select autodoc:
autodoc: automatically insert docstrings from modules (y/N) [n]: y
Then, in the generated index.rst I usually add modules to include all the modules automatically (watch identation).
.. toctree::
:maxdepth: 4
modules
After this sphinx-apidoc -o does generates documentation for me.
I wrote a guide to use Sphinx for Python code used in embedded systems, but the first steps of the Guide might be useful to you as well:
How to generate sphinx documentation for python code running in an embedded system
[EDIT]
Here is a step-by-step list:
Create documentation folder: mkdir doc
├── doc/
└── lib.py
cd doc
sphinx-quickstart
(Be sure to select autodoc: y
, Makefile: y
)sys.path.insert(0, os.path.abspath('..'))
Edit index.rst and specify modules in the toctree:
.. toctree::
:maxdepth: 2
modules
sphinx-apidoc -o . ..
make html
firefox _build/html/index.html