如何为一个包含函数的文件进行文档化？

Question

如何为一个包含函数的文件进行文档化？

10

我有一个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之后，我使用我的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:

有人能逐步解释一下我必须做什么吗？

- natalia

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- jcarballo · Accepted Answer

首先，当你运行 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代码生成文档的指南，但指南的前几步对您也可能有用:

如何为在嵌入式系统中运行的Python代码生成sphinx文档

[编辑]

以下是逐步说明：

创建 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