我可以在 Python docstring 中使用 :noindex: 和 Sphinx autodoc 吗？

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，在这种情况下，无需在 .rst?

中明确定义 MainModel 和 to 函数

Answer 1

:no-index: 是在 Sphinx 和 autodoc 指令.

下使用的选项

来自 Sphinx 域和指令：

Basic Markup

If you want to typeset an object description, without even making it available for cross-referencing, you can give the directive option flag :noindex: (which implies :noindexentry:)

来自自动文档扩展：

Options and advanced usage - Directives

All autodoc directives support the noindex flag option that has the same effect as for standard py:function etc. directives: no index entries are generated for the documented object (and all autodocumented members)

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

.. directive::
   :noindex:

在文档字符串中声明指令总是错误的。你放在文档字符串中的内容总是 docstrings sections. Notice there are several styles to writing docstrings （Numpy 风格，Google 风格，正常的 reST），但其中 none 接受文档字符串中的指令。您在 .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
    """

我可以在 Python docstring 中使用 :noindex: 和 Sphinx autodoc 吗？

Can I use :noindex: in Python docstring with Sphinx autodoc?

python

python-sphinx

autodoc

设置

尝试次数