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

sphinx-quickstart从新doc目录内部运行并按 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 教程文档。

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

sourcedir必须指向 Python 包。

文档中的下面还有一个警告：

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

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