我有一个 python 文件,其中包含函数 (lib.py),但没有类。每个函数都有以下样式:
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
我只想用 Sphinx 记录每个函数(输入和输出)。
完成 sphinx-quickstart 后,我在 conf.py 中用我的 lib.py 定义了路径。 但是输出的 HTML 文件(欢迎页面)是空的。
如果我在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
没关系,它在 html 文件中显示了输入和输出。 但是如何自动完成呢?
通常,我认为,它必须在 sphinx-apidoc -o 之后在 lib.rst 中执行, 但在 lib.rst 中只有:
lib module
==================
.. automodule:: lib
:members:
:undoc-members:
:show-inheritance:
有人可以一步一步地向我解释我必须做什么吗?
最佳答案
首先,当您运行 sphinx-quickstart 时,请务必选择 autodoc:
autodoc: automatically insert docstrings from modules (y/N) [n]: y
然后,在生成的 index.rst 中,我通常会添加 modules 以自动包含所有模块(watch identation)。
.. toctree::
:maxdepth: 4
modules
此后 sphinx-apidoc -o 确实为我生成了文档。
我写了一份指南,将 Sphinx 用于嵌入式系统中使用的 Python 代码,但该指南的第一步可能对您也有用:
How to generate sphinx documentation for python code running in an embedded system
[编辑]
这是一个分步列表:
- 创建 lib.py
创建文档文件夹:
mkdir doc
├── doc/ └── lib.py
- 输入doc/:
cd doc
- 执行
sphinx-quickstart
(一定要选择autodoc: y
,Makefile: y
) - 编辑 conf.py 以指定 sys.path:
sys.path.insert(0, os.path.abspath('..'))
编辑 index.rst 并在 toctree 中指定 modules:
.. toctree:: :maxdepth: 2 modules
- 执行
sphinx-apidoc -o 。 ..
- 生成 html 输出:
make html
- 查看您的文档:
firefox _build/html/index.html
关于python - 如何用函数记录一个文件?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/20354768/