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

Question

I am trying to build documentation with sphinx, and cannot figure out how to use :noindex:.

Setup

I'm using following extensions:

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

My .rst file contains this routine from autodoc to generate documentation:

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

This points to main_model.py file, which contains:

class MainModel:
    ... some functions ...

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

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

The :noindex: above doesn't work. It just shows up in generated documentation as normal text.

Attempts

I have tried these three ways of putting index:

# 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.
    """

But neither worked.

Am I missing something obvious, or is :noindex: not supposed to be used outside of .rst files? If that's the case then is there any way I can still leverage autodoc, in this case without explicitly defining MainModel and to functions in .rst?

score 6 · Accepted Answer · answered Mar 22 '21 at 01:58

The :no-index: is an option used under Sphinx and autodoc directives.

From Sphinx domains and directives:

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:)

From the autodoc extension:

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)

What this means is that when you declare a .. directive:: with the usual syntax, the :noindex: option goes underneath the directive (mind the indentation):

.. directive::
   :noindex:

Declaring a directive inside a docstring is invariably a mistake. What you put inside a docstring are always docstrings sections. Notice there are several styles to writing docstrings (Numpy style, Google style, normal reST) but none of them take directives in the docstrings. You write the directives in the .rst files.

So in your case you'd write the .rst like this:

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

You could also try

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

and the docstring would like this:

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

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

or using Google style docstrings

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

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

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

Setup

Attempts

1 Answers1