自动生成所有Python包内容的文档

10 浏览
0 Comments

自动生成所有Python包内容的文档

我正在尝试使用Sphinx为我的代码库自动生成基本文档。然而，我在指导Sphinx递归扫描我的文件时遇到了困难。

我的Python代码库的文件夹结构如下：


└── src
    └── mypackage
        ├── __init__.py
        │   
        ├── subpackageA
        │   ├── __init__.py
        │   ├── submoduleA1
        │   └── submoduleA2
        │   
        └── subpackageB
            ├── __init__.py
            ├── submoduleB1
            └── submoduleB2

我在中运行了sphinx-quickstart，所以现在我的结构看起来像这样：


├── src
│   └── mypackage
│       ├── __init__.py
│       │
│       ├── subpackageA
│       │   ├── __init__.py
│       │   ├── submoduleA1
│       │   └── submoduleA2
│       │
│       └── subpackageB
│           ├── __init__.py
│           ├── submoduleB1
│           └── ubmoduleB2
│
├── index.rst
├── _build
├── _static
└── _templates

我已经阅读了快速入门教程，虽然我仍在努力理解文档，但它的措辞让我担心Sphinx是否假设我将手动为代码库中的每个模块/类/函数创建文档文件。

然而，我注意到了"automodule"语句，并在快速入门时启用了autodoc，所以我希望大部分文档可以自动生成。我修改了我的conf.py文件，将src文件夹添加到sys.path中，然后修改了我的index.rst文件以使用automodule。现在我的index.rst文件如下所示：

目录：

.. toctree::

:maxdepth: 2

索引和表格

==================

* :ref:`genindex`

* :ref:`modindex`

* :ref:`search`

.. automodule:: alphabuyer

:members:

我在子包中定义了几十个类和函数。然而，当我运行：

sphinx-build -b html . ./_build

它报告：

updating environment: 1 added, 0 changed, 0 removed

而且似乎无法导入我的包中的任何内容。查看生成的index.html文件，在"目录："旁边没有显示任何内容。索引页面只显示"mypackage (module)"，但点击它显示它也没有任何内容。

如何指导Sphinx递归解析一个包，并自动生成遇到的每个类/方法/函数的文档，而不必手动列出每个类？

0