如何用功能记录一个文件? [英] How to document one file with functions?

问题描述

我有一个带函数(lib.py)且没有类的python文件.每个函数具有以下样式:

I have a python file with functions (lib.py), without classes. Each function has the following style:

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记录每个函数(输入和输出).

I just want to document each function (inputs and outputs) with Sphinx.

完成 sphinx-quickstart 后，我用lib.py在 conf.py 中定义了路径. 但是输出的HTML文件(欢迎页面)为空.

After doing sphinx-quickstart, I defined the path in conf.py with my lib.py. But the output HTML file (welcome page) is empty.

如果我在 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文件形式显示输入和输出. 但是如何自动做到呢?

it is ok, it shows the inputs and outputs in html file. But how to do it automatically?

通常，我认为在执行 sphinx-apidoc -o 之后，必须在 lib.rst 中执行此操作， 但在 lib.rst 中只有:

Normally, I think, it must to do it in lib.rst after doing sphinx-apidoc -o, but in lib.rst there is only:

lib module
==================

.. automodule:: lib
    :members:
    :undoc-members:
    :show-inheritance:

有人可以一步一步解释我该怎么做吗?

Can somebody explain me step by step what I must do exactly?

推荐答案

首先，运行 sphinx-quickstart 时，请确保选择 autodoc :

First, when you run sphinx-quickstart, be sure you select autodoc:

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

然后，通常在生成的 index.rst 中添加 modules 以自动包括所有模块(手表标识).

Then, in the generated index.rst I usually add modules to include all the modules automatically (watch identation).

.. toctree::
   :maxdepth: 4

   modules

此 sphinx-apidoc -o 确实会为我生成文档.

After this sphinx-apidoc -o does generates documentation for me.

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

I wrote a guide to use Sphinx for Python code used in embedded systems, but the first steps of the Guide might be useful to you as well:

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

这是分步列表:

1. 创建lib.py

2. 创建文档文件夹: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中指定模块:

Enter doc/: cd doc

Execute sphinx-quickstart (Be sure to select autodoc: y, Makefile: y)

Edit conf.py to specify sys.path: sys.path.insert(0, os.path.abspath('..'))

Edit index.rst and specify modules in the toctree:

.. toctree::
    :maxdepth: 2

    modules

执行sphinx-apidoc -o . ..

生成html输出:make html

查看您的文档:firefox _build/html/index.html

Execute sphinx-apidoc -o . ..

Generate the html output: make html

View your documentation: firefox _build/html/index.html

这篇关于如何用功能记录一个文件?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！