如何将自动模块添加到Sphinx Toctree

2022-04-22 00:00:00 python python-sphinx

问题描述

我希望Sphinx文档的左侧菜单包含项目的模块，并且希望从主模块的__init__.py文件定义此内容。这就是我正在尝试的：

__init__.py
'''
Components platform:
--------------------

* language: python
* rest framework: flask-restful
* testing: pytest
* documentation: sphinx

.. toctree::
   :maxdepth: 1
   :caption: Contents:

   .. automodule:: sacbeh.main

   .. automodule:: sacbeh.api

   .. automodule:: sacbeh.controllers
'''

问题是，当我运行make html时，我收到以下错误：

/Users/hugovillalobos/Documents/Code/sacbeh-project/sacbeh-backend/sacbeh/__init__.py:docstring of sacbeh:9: WARNING: toctree contains reference to nonexisting document '.. automodule:: sacbeh.main'
/Users/hugovillalobos/Documents/Code/sacbeh-project/sacbeh-backend/sacbeh/__init__.py:docstring of sacbeh:9: WARNING: toctree contains reference to nonexisting document '.. automodule:: sacbeh.api'
/Users/hugovillalobos/Documents/Code/sacbeh-project/sacbeh-backend/sacbeh/__init__.py:docstring of sacbeh:9: WARNING: toctree contains reference to nonexisting document '.. automodule:: sacbeh.controllers'

我还没有找到实现这一点的方法。

编辑

我知道事情并不是这样的。我已经使用REST文件使其工作，但我正在尝试找到一种用尽可能少的额外文件来记录我的项目的方法，所以我想尽可能使用文档字符串。

我相信我的问题是正确的，但不一定可行。

解决方案

.. toctree:: directive中的每一行都称为条目。条目不能为autodoc directives。

您有4个条目选项：

Entries

目录树中的文档标题将自动从引用文档的标题中读取。

  1. 只需使用文件名作为条目，不带扩展名。

    .. toctree::

   file_name_without_the_rst_extension

Entries

(...)您可以使用与REST超链接类似的语法指定显式标题和目标

  1. 同上，但为条目指定了服装标题。

    .. toctree::

   Whatever title you want to write <file_name_without_the_rst_extension>

Additional options

您可以通过提供GLOB标志选项，在toctree指令中使用"GLOBING"。然后将所有条目与可用文档列表进行匹配，并按字母顺序将匹配项插入列表。

(...)

这首先包括名称以INTRO开头的所有文档，然后是Recipe文件夹中的所有文档，然后是所有剩余的文档(当然，包含该指令的文档除外)。

  1. 球状图案。可以是目录的内容，也可以是部分文件名的所有匹配项。

    .. toctree::
   :glob:

   intro*
   recipe/*
   *

Additional options

特殊条目名称self代表包含toctree指令的文档。如果您想要从toctree生成一个"站点地图"，这是很有用的。 或

  1. 该条目还可以是特殊名称self，在这种情况下，包含toctree的.rst将作为条目添加。

    .. toctree::

   self

  2. 有一个未记录的功能，它使用point(2.)中解释的语法将http://链接添加为条目。检查此帖子"External Relative Link in Sphinx toctree directive"

话虽如此，问题中的问题在几个方面都是不正确的。

  1. 您不能将.. automodule::添加为.. toctree::条目。(如上所示)。

  2. 您不应该在文档字符串中放入.. toctree::。这在概念上是错误的，文档字符串被用来记录它们被设置为__doc__属性的对象的API(签名和简短评论)。

以上已经是很长的解释了，但我认为真正解决问题的是：

  1. 记录__init__.py文件的情况很少发生。主要原因是，没有人使用您的代码/文档：from __init__ import something，对吗？！

解决方案是什么？此：

用于记录类的your_package.rst文件(在Python中，包也是一个模块)应该如下所示。您不必在__init__.py中放置一个文档字符串，但您需要有一个.rst文件与您放置..automodule::指令的包相对应。

------------
your_package
------------

   .. automodule:: sacbeh.main
      :members:

   .. automodule:: sacbeh.api
      :members:

   .. automodule:: sacbeh.controllers
      :members:

链接上述your_package.rst的index.rst应如下所示：

-----
index
-----

.. toctree::
   :maxdepth: 1
   :caption: Contents:

   your_package

相关文章