企业官网建设流程全解析

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

Cer*_*rin 51

我这边正打算试着去弄那个能给我的代码库自动生成基础文档的事情呢, 可是, 我在想要怎么跟工具说明, 让它能够递归地去扫描我们自己的那些文件的时候, 感觉特别费劲, 完全搞不定。

我的那个代码里面, 所使用的文件夹排列办法是下面这样的。

src

mypackage

__init__.py

subpackageA

__init__.py

submoduleA1

submoduleA2

subpackageB

__init__.py

submoduleB1

submoduleB2

Run Code ( Code )

我自己动手跑了那个流程, 于是目前的整体架构变成了下面这样:

src

mypackage

__init__.py

subpackageA

__init__.py

submoduleA1

submoduleA2

subpackageB

__init__.py

submoduleB1

submoduleB2

index.rst

_build

_static

_templates

Run Code ( Code )

我这边已经把快速入门那个教程给看完了, 虽然我还在费劲琢磨那些文档里的意思, 不过它那说话的调调让我有点犯嘀咕, 生怕它心里头已经想当然地认定了, 我要去一个个手动建文档, 好把代码里头的每一个模块、还有类和函数这些玩意儿的说明文件全都给写出来。

然而, 我确实注意到了那个语句的事情。然后我在快速入门的期间把它给启用了。所以我期望大多数的文档都能够自动地被生成出来。我去修改了我的conf.py这个文件的内容来把我的src文件夹添加到sys.path里面去。

接着我还修改了我的index.rst这个文件的内容以使用自动模块的相关功能。因此呢, 我现在所看到的情况是, 我的index.rst看起来像是这个样子:

Contents:

.. toctree::

:maxdepth: 2

Indices and tables

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

* :ref:`genindex`

* :ref:`modindex`

* :ref:`search`

.. automodule:: alphabuyer

:members:

Run Code ( Code )

我在子包中定义了几十个类和函数。可是, 当我运行的时候:

sphinx-build -b html . ./_build

Run Code ( Code )

它报道:

updating environment: 1 added, 0 changed, 0 removed

Run Code ( Code )

这看起来好像是没办法把我自己包里面包含的那些东西都给导入进去。然后就去仔细查看那个生成的index.html这个文件。发现它在那个冒号旁边的位置上头, 根本就没有显示出任何的内容来。

而且那个索引页面也仅仅只是显示出了“(模块)”这几个字而已。可是当我尝试着去点击它的时候,就发现它也压根儿就没有任何内容呈现出来。

我们具体应该怎样去指导那个递归解析包的工具, 让它能够自动地、逐个地生成它所遇见的类以及方法和函数的文档资料, 而不是需要我们自己动手一个一个地把这些内容都列出来呢?