如何用功能记录一个文件? [英] How to document one file with functions?
问题描述
我有一个带函数(lib.py)且没有类的python文件.每个函数具有以下样式:
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
我只想用Sphinx记录每个函数(输入和输出).
I just want to document each function (inputs and outputs) with Sphinx.
完成 sphinx-quickstart 后,我用lib.py在 conf.py 中定义了路径. 但是输出的HTML文件(欢迎页面)为空.
After doing sphinx-quickstart, I defined the path in conf.py with my lib.py. But the output HTML file (welcome page) is empty.
如果我在 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文件形式显示输入和输出. 但是如何自动做到呢?
it is ok, it shows the inputs and outputs in html file. But how to do it automatically?
通常,我认为在执行 sphinx-apidoc -o 之后,必须在 lib.rst 中执行此操作, 但在 lib.rst 中只有:
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?
推荐答案
首先,运行 sphinx-quickstart 时,请确保选择 autodoc :
First, when you run sphinx-quickstart, be sure you select autodoc:
autodoc: automatically insert docstrings from modules (y/N) [n]: y
然后,通常在生成的 index.rst 中添加 modules 以自动包括所有模块(手表标识).
Then, in the generated index.rst I usually add modules to include all the modules automatically (watch identation).
.. toctree::
:maxdepth: 4
modules
此 sphinx-apidoc -o 确实会为我生成文档.
After this sphinx-apidoc -o does generates documentation for me.
我编写了一个指南,将Sphinx用于嵌入式系统中使用的Python代码,但是该指南的第一步可能对您也很有用:
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:
如何为在嵌入式系统中运行的python代码生成sphinx文档
这是分步列表:
- 创建lib.py
-
创建文档文件夹:
mkdir doc
├── doc/
└── lib.py
cd doc
sphinx-quickstart
(确保选择autodoc: y
,Makefile: y
)sys.path.insert(0, os.path.abspath('..'))
编辑index.rst并在toctree中指定模块:
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
sphinx-apidoc -o . ..
make html
firefox _build/html/index.html
这篇关于如何用功能记录一个文件?的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!