Python Sphinx：如何用函数记录一个文件？

Question

我有一个带有函数（lib.py）的python文件，没有类。每个函数具有以下样式：

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快速启动之后，我用lib.py在conf.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

然后，在生成的索引中，rst通常添加模块以自动包含所有模块（监视标识）。

.. 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::
       :maxdepth: 2
   
       modules
   

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