3

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.

Community
  • 1
  • 1
sb933
  • 101
  • 7
  • 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 Apr 12 '17 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 Apr 19 '17 at 15:23
  • 2
    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 Apr 19 '17 at 15:30

1 Answers1

1

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.

Mad Physicist
  • 107,652
  • 25
  • 181
  • 264