python-sphinx - 将 sphinx 用于非常基本的结构

Question

这是我的文件层次结构：

信息救援
|
|_ 源
|
|_ _ _ 包括
|
|_ _ _ _ _ i1.py
|_ _ _ _ _ i2.py
|_ _ _ _ _ init .py
|
|_ _ _ 实用程序
|
|_ _ _ _ _ u1.py
|_ _ _ _ _ u2.py
|_ _ _ _ _ init .py
|
|_ _ _ 文档
|
|_ _ _ _ _ index.rst
|_ _ _ _ _ project.rst
|_ _ _ _ _ contact.rst
|_ _ _ _ _ api
|
|_ _ _ _ _ _ _ api.rst
|_ _ _ _ _ _ _ 包括.rst |_ _
_ _ _ _ _ utils.rst

我正在使用 Sphinx 生成文档。与 sphinx 相关的所有内容都在doc目录中。

我的 index.rst：

.. InfoRescue documentation master file, created by
   sphinx-quickstart on Sun Sep 15 13:52:12 2013.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to InfoRescue's documentation!
======================================

Contents:
========

.. toctree::
   :maxdepth: 2

   project
   api/api
   contact

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

api.rst：

InfoRescue API
**********

.. toctree::
    :glob:
    :maxdepth: 1

    **

现在在 utils 里面有 .py 文件。这两个文件都不包含类和直接代码，都只包含函数。要记录我可以使用的功能.. autofunction:: utils.u1.functionName。这工作正常，但我必须为每个功能都这样写。有什么简单的方法可以简单地包含所有功能吗？

假设包含目录中的两个文件都不包含类，并且只包含一些（直接）代码。如何为其生成文档，即使用哪个自动指令？

此外，utils 和包含目录中的init .py 文件都是空的。我做了这两个，以便我可以从 .rst 文件访问这些目录中的文件。有没有其他方法可以让我不必创建 _ init _.py 文件？

Answer 1

“__init__.py”文件的存在将目录标记为 Python包。你不需要为Sphinx 这样做。相反，您可以通过编辑“src/doc/conf.py”文件将目录内容放在 Python 路径上，在“import sys, os”行之后添加行，例如：

sys.path.insert(0, os.path.abspath(os.path.join('..', '..', 'utils')))
sys.path.insert(0, os.path.abspath(os.path.join('..', '..', 'includes')))

当然，如果您将文档字符串放入“utils/__init__.py”和“includes/__init__.py”并尝试使用 Sphinx 和这些路径添加来记录它们，那么您将不得不做更多的工作。

Answer 2

Sphinx 有一个名为autosummary的默认扩展，它能够扫描您的源代码并自动生成包含必要autofunction指令的 Sphinx 输入文件。

Answer 3

自动汇总生成表格

您可能希望在 .rst 文件中使用类似automodule的东西：

.. automodule:: i1
   :members:

Answer 4

对于（直接）代码，您需要在文件的第一个文档字符串中提供该文档。

Answer 5

改进@BarryPie 上面的答案，并且遇到必须sys.path.insert为所有子包添加所有的问题，我在我的conf.py：

for root, dirs, files in os.walk('../../src'): # path to my source code
    if '__pycache__' not in root: #__pycache__ folder excluded
        sys.path.insert(0, os.path.abspath(root))

并且所有子包都按要求导入。