如何在 Sphinx 中定义应该使用哪些 .rst 文件和目录？答案

【问题标题】：How I can define in Sphinx which .rst files and directories should be used?如何在 Sphinx 中定义应该使用哪些 .rst 文件和目录？
【发布时间】：2012-10-19 13:32:00
【问题描述】：

如何在 Sphinx 中定义应该使用哪些 .rst 文件和目录？

我想在我的测试/构建/文档脚本中包含一个自动文档生成器。 sphinx-quickstart 在我的工作区中执行并创建了一个 index.rst 文件。由于 Sphinx 使用重组的文本文件作为文档，我在工作区中导航并使用 sphinx-autogen 手动创建它们。它生成了 tasks.rst 文件（见下文）。

当我使用“make html”时，我收到了几个警告：

警告：自动模块的签名无效（u'tasks/add_to_config'）

警告：autodoc 无法导入/查找模块'tasks.add_to_config'，它报告错误：“没有名为wl_build.tasks 的模块”，请检查您的拼写和sys.path

警告：不知道要导入哪个模块来自动记录 u'tasks/add_to_config'（尝试在文档中放置“模块”或“当前模块”指令，或给出明确的模块名称)

...

我的 index.rst

Welcome to build's documentation!
====================================

Contents:

.. toctree::
   :maxdepth: 2

.. automodule:: tasks/add_to_config
   :members:

.. automodule:: tasks/build_egg
   :members:

tasks.rst

tasks Package
=============

:mod:`tasks` Package
--------------------

.. automodule:: tasks.__init__
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`add_to_config` Module
---------------------------

.. automodule:: tasks.add_to_config
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`build_egg` Module
-----------------------

.. automodule:: tasks.build_egg
    :members:
    :undoc-members:
    :show-inheritance:

【问题讨论】：

标签： python python-sphinx restructuredtext autodoc

【解决方案1】：

尝试将 index.rst 文件中的 / 字符替换为句点 (.)

像这样：

Welcome to build's documentation!
====================================

Contents:

.. toctree::
   :maxdepth: 2

.. automodule:: tasks.add_to_config
   :members:

.. automodule:: tasks.build_egg
   :members:

看看有没有帮助。

如果 Sphinx 仍然找不到要记录的代码，那么您可能需要修改您的 PYTHONPATH 或更改您的 conf.py 文件中的 sys.path 以帮助 Sphinx 找到它正在寻找的内容。

【讨论】：