我可以在 Python 文档字符串中使用：noindex: 和 Sphinx 自动文档吗？

Question

我正在尝试使用 sphinx 构建文档，但无法弄清楚如何使用:noindex: 。

设置

我正在使用以下扩展：

extensions = [
    "sphinx.ext.napoleon",
    "sphinx.ext.todo",
    "sphinx.ext.viewcode",
    "sphinx.ext.autodoc",
    "sphinx_rtd_theme",
    "m2r2",
]

我的.rst文件包含从 autodoc 生成文档的这个例程：

.. automodule:: squid.models.main_model
   :members:
   :undoc-members:
   :show-inheritance:

这指向main_model.py文件，其中包含：

class MainModel:
    ... some functions ...

    def to(self, device):
        """
        :noindex:

        Copy of `nn.Module` `to` function but adjusts for stuff.
        """

:noindex:上面不起作用。 它只是在生成的文档中显示为普通文本。

尝试

我尝试了这三种放置索引的方法：

# Attempt 1
def to(self, device):
    """
    :noindex:

    Copy of `nn.Module` `to` function but adjusts for stuff.
    """

# Attempt 2
def to(self, device):
    """
    .. py:function:: to
      :noindex:

      Copy of `nn.Module` `to` function but adjusts for stuff.
    """

# Attempt 3
def to(self, device):  # :noindex:
    """Copy of `nn.Module` `to` function but adjusts for stuff.
    """

但都没有奏效。

我是否遗漏了一些明显的东西，或者:noindex:不应该在.rst文件之外使用？ 如果是这种情况，那么有什么方法我仍然可以利用 autodoc，在这种情况下，无需显式定义MainModel和.rst to函数？

Answer 1

:no-index:是 Sphinx 和 autodoc指令下使用的选项。

来自 Sphinx 域和指令：

基本标记

如果您想排版 object 描述，甚至不使其可用于交叉引用，您可以提供指令选项标志:noindex: （这意味着:noindexentry: ）

从自动文档扩展：

选项和高级用法 - 指令

所有 autodoc 指令都支持noindex标志选项，该选项与标准 py:function 等指令具有相同的效果：没有为记录的 object （和所有自动记录的成员）生成索引条目

这意味着当您使用通常的语法声明.. directive::时， :noindex:选项位于指令下方（注意缩进）：

.. directive::
   :noindex:

在文档字符串中声明指令总是错误的。 您放在文档字符串中的始终是文档字符串部分。 请注意，有几个 styles 用于编写文档字符串（Numpy 样式、Google 样式、普通 reST），但它们都没有在文档字符串中使用指令。 您在.rst文件中编写指令。

所以在你的情况下，你会这样写.rst ：

.. automodule:: squid.models.main_model
   :members:
   :undoc-members:
   :show-inheritance:
   :noindex:

你也可以试试

.. automethod:: squid.models.main_model.to
   :noindex:

并且文档字符串会这样：

def to(self, device):
    """
    Copy of `nn.Module` `to` function but adjusts for stuff.

    :param device:
    :type device: str
    """

或使用 Google 风格的文档字符串

def to(self, device):
    """
    Copy of `nn.Module` `to` function but adjusts for stuff.

    Args:
        device (str): The path of the file to wrap
    """