How do I selectively hide module docstrings in sphinx autodoc?

Question

In autodoc, I know you can hide the docstrings for all modules as described here: Exclude module docstring in autodoc

But is there a way to do this for some modules and not others, possibly with some parameter passed to automodule? In other words, for a given module, I want to sometimes include the docstrings and sometimes skip it. If I do:

.. automodule:: foo :members: foo, foo.bar

Sphinx generates the docstrings for foo and foo.bar. However, doing

.. automodule:: foo :members: foo.bar

will not hide the module docstring.

I think what you are looking for is in the linked answer. The code in that answer does not hide the docstrings for all modules; it only hides it for the module called yourmodule. — mzjn
– mzjn, Commented Apr 12, 2017 at 15:29
@mzjn thanks! What you say is correct but that code in conf.py applies to all instances of a module in a given project. For example, in some files, I'd like to exclude the docstring. In other files, I'd like to keep it. — sb933
– sb933, Commented Apr 19, 2017 at 15:23
But you could expand the code in my answer and use something like if what == "module" and name in ("module1", "module2", "module3"):. Wouldn't that work? Am I misunderstanding something? — mzjn
– mzjn, Commented Apr 19, 2017 at 15:30

Mad Physicist · Accepted Answer · 2018-05-04 19:28:31Z

To hide the docstring of a module, you use the corresponding plain py domain version of the directive: either py:module or py:currentmodule. The former is for the main place you document the module, and should only occur once. The latter is for other places where you want the same name resolution properties, but without making it the official documentation spot for the module.

All the autodoc domain directives will respect the naming scope set by the regular py domain directives. From the docs:

Note

Just as py:class respects the current py:module, autoclass will also do so. Likewise, automethod will respect the current py:class.

Collectives™ on Stack Overflow

How do I selectively hide module docstrings in sphinx autodoc?

1 Answer 1

Comments

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Linked

Related