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

从新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 tutorial documentation of packages。

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

  

sourcedir 必须指向Python包。

在文档中还有一个警告：

  

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

如果没有看到您的代码，我会从__init__.py文件开始，看看是否能解决这个问题。