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-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中,我通常会添加模块以自动包含所有模块(监视标识).

.. toctree::
   :maxdepth: 4

   modules

在此之后,sphinx-apidoc -o会为我生成文档.

我编写了一个指南,将Sphinx用于嵌入式系统中使用的Python代码,但本指南的第一步也可能对您有用:

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

[编辑]

这是一个循序渐进的列表:

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中指定模块:

   .. toctree::
       :maxdepth: 2
   
       modules
   

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