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

问题描述

我希望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个条目选项：

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

   .. toctree::
   
      file_name_without_the_rst_extension
   

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

   .. toctree::
   
      Whatever title you want to write <file_name_without_the_rst_extension>
   

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

   .. toctree::
      :glob:
   
      intro*
      recipe/*
      *
   

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

这篇关于如何将自动模块添加到Sphinx Toctree的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！