如何使用 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)

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

安装狮身人面像：

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 时，我看到的只是以下内容，并且没有来自我在原始脚本中插入的文档字符串的任何信息。单击模块索引会给出未找到文件的错误。这是为什么呢？

编辑： 完成上述所有步骤后，我添加了一个文件夹 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 必须指向 Python 包。

在文档的下方还有一个警告：

如果您记录脚本（而不是库模块），请确保它们的主例程受到if __name__ == '__main__' 条件的保护。

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