Question

这是我的文件层次结构：

InfoRescue
|
| _ src
|
| _ _ _包括
|
| _ _ _ _ _ i1.py
| _ _ _ _ _ i2.py
| _ _ _ _ _ init .py
|
| _ _ _ utils
|
| _ _ _ _ _ u1.py
| _ _ _ _ _ u2.py
| _ _ _ _ _ init .py
|
| _ _ _ doc
|
| _ _ _ _ _ index.rst
| _ _ _ _ _ project.rst
| _ _ _ _ _ contact.rst
| _ _ _ _ _ api
|
| _ _ _ _ _ _ _ api.rst
| _ _ _ _ _ _ _ includes.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。这是正常的，但我必须为每个功能写这样的。 是否有简单的方法可以简单地包含所有功能？

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

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

Answer 1

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

Answer 2

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

Answer 3

“__ 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')))

当然，如果你将docstrings放在“utils / __ init__.py”和“includes / __ init__.py”中并尝试使用Sphinx和这些路径添加来记录它们，那么你将需要做更多的工作。 / p>

Answer 4

autosummary生成一个表

您可能希望在.rst文件中使用automodule之类的内容：

.. automodule:: i1
   :members:

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))

并根据要求导入所有子包。

使用sphinx作为非常基本的结构

5 个答案: