python - 如何使用 Sphinx 记录简单的 Python 脚本？

Question

我已经阅读了大量的 Sphinx 教程，但我仍然不知道如何使 Sphinx 文档成为像这样的简单 Python 脚本:

def addNumbers(a):
    """This function adds one to the given number.

    :param a: The name to use
    :type a: int

    """
    b = a + 1
    print b

addNumbers(5)

以下是我所做的步骤。我错过了什么？

安装Sphinx:

pip install sphinx

在我的项目目录中创建一个文档目录:

mkdir docs

从新的 doc 目录中运行 sphinx-quickstart 并按 Enter 键回答除这两个问题之外的所有问题:

Separate source and build directories (y/n) [n]: y
autodoc: automatically insert docstrings from modules (y/n) [n]: y

这使得我的项目目录结构变成这样:

myproject/ 
|-- docs/
    |-- build/
    |-- source/
    make.bat
    Makefile
|-- mycode/ 
    myscript.py 

打开conf.py，取消注释以下行，并添加我的代码所在文件夹的路径:

import os
import sys
sys.path.insert(0, os.path.abspath('C:\myproject\mycode'))

从我的 docs 目录运行以下命令:

make html

这给了我以下确认，没有错误:

现在，当我打开 C:\myproject\docs\build\html\index.html 时，我看到的只是以下内容，并且没有来 self 插入原始脚本中的文档字符串的信息。单击模块索引会出现文件未找到错误。这是为什么？

编辑:完成上述所有步骤后，我添加了一个文件夹 mypackage 并将包含我的代码的文件复制到其中，使目录内容如下所示:

myproject/ 
|-- docs/
    |-- build/
    |-- source/
    make.bat
    Makefile
|-- mycode/ 
    myscript.py 
|-- mypackage/ 
    myscript.py 

然后我从 doc 目录运行以下命令:

sphinx-apidoc -f -o source/ ../mypackage/
make html

现在单击模块索引会显示以下内容:

然后点击myscript给出:

现在的问题是为什么我的主脚本 myscript.py 列在模块下而不是列在文档的主页上？

Answer 1

需要 __init__.py 文件才能使 Python 将目录视为包含包。请参阅Python tutorial documentation of packages .

我的猜测是，sphinx-apidoc 将您的脚本识别为脚本，而不是包，因为您省略了 __init__.py 文件。根据 sphinx-apidoc 的文档:

sourcedir must point to a Python package.

文档中的警告下方还有一个警告:

If you document scripts (as opposed to library modules), make sure their main routine is protected by a if __name__ == '__main__' condition.

在没有看到您的代码的情况下，我会从 __init__.py 文件开始，看看是否可以解决问题。