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

如何解决我可以在带有 Sphinx 自动文档的 Python 文档字符串中使用 :noindex: 吗？

我正在尝试使用 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 中明确定义 to 和 .rst 函数？

解决方法

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

来自 Sphinx 域和指令：

Basic Markup

如果你想排版一个对象描述，甚至不让它可用于交叉引用，你可以给指令选项标志:noindex:（这意味着:noindexentry:）

来自自动文档扩展：

Options and advanced usage - Directives

所有 autodoc 指令都支持 noindex 标志选项，其效果与标准 py:function 等指令的效果相同：不为文档对象（和所有自动文档成员）生成索引条目

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

.. directive::
   :noindex:

在文档字符串中声明指令总是一个错误。您在文档字符串中放入的内容始终是 docstrings sections。请注意，有 several styles to writing docstrings（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
    """