10

我有一个带有函数（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:

有人可以逐步解释我必须做什么吗？

4

1 回答 1

17

首先，当你运行sphinx-quickstart时，一定要选择autodoc：

autodoc: automatically insert docstrings from modules (y/N) [n]: y

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

.. toctree::
   :maxdepth: 4

   modules

在这个sphinx-apidoc -o确实为我生成文档之后。

我为在嵌入式系统中使用的 Python 代码编写了使用 Sphinx 的指南，但该指南的第一步可能对您也有用：

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

[编辑]

这是一个分步列表：

  1. 创建 lib.py

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

    ├── doc/
└── lib.py
  3. 输入文档/：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
于 2013-12-03T15:36:17.183 回答