python - 如何用函数记录一个文件？

Question

我有一个 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:

有人可以一步一步地向我解释我必须做什么吗？

Answer 1

首先，当您运行 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

[编辑]

这是一个分步列表:

1. 创建 lib.py

2. 创建文档文件夹:mkdir doc

   ├── doc/
   └── lib.py
   

3. 输入doc/: cd doc
4. 执行sphinx-quickstart(一定要选择autodoc: y, Makefile: y)
5. 编辑 conf.py 以指定 sys.path:sys.path.insert(0, os.path.abspath('..'))

6. 编辑 index.rst 并在 toctree 中指定 modules:

   .. toctree::
       :maxdepth: 2
   
       modules
   

7. 执行 sphinx-apidoc -o 。 ..
8. 生成 html 输出:make html
9. 查看您的文档:firefox _build/html/index.html