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-quickstart之后，我使用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

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

.. 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-Sphinx：如何使用函数记录一个文件？

1 个答案: