How can I change `add_module_names` to `False` for specific modules?

Question

How can I change add_module_names to False for specific modules?

I have the following structure:

src/
    / _foo
       some_file.py
    / bar
       some_other_file.py

I would like that all functions documents with .. autofunction:: from the _foo module to have the name of the module hidden, while all functions of the bar module display the name.

Is there a way for me to perform this configuration by module, or even individually for each function?

What did you try in your .rst? We kind of do this in Pyramid docs. See [HTML](https://docs.pylonsproject.org/projects/pyramid/en/latest/api/authentication.html#pyramid.authentication.extract_http_basic_credentials) and [.rst source](https://docs.pylonsproject.org/projects/pyramid/en/latest/_sources/api/authentication.rst.txt) for `extract_http_basic_credentials`. The module name appears as the page title, but can be removed. You need to indent the function name under the module name as in the example. — Steve Piercy, Nov 24 '20 at 07:22
@StevePiercy your solution [uses a different value for `add_module_names`](https://github.com/Pylons/pyramid/blob/1.10-branch/docs/conf.py#L119). The problem with the `True` value is Sphinx will automatically prepend everywhere - and the question is about making an exception in that scenario. I write my `.rst` like you because it allows for finer control of how the names are rendered. — bad_coder, Nov 24 '20 at 17:00

bad_coder · Accepted Answer · 2020-11-24T05:21:58.420

The add_module_names boolean is a general configuration setting in conf.py. It reflects your project-wide choice to render module names with objects, it can't be changed for a specific module. An exception to the rule can be implemented but the workaround requires some extra writing.

The solution is to explicitly declare the members you want using a domain directive, in this case .. py:function::. This lets you specify the signature and the fully qualified name - PEP 3155. The drawback is you won't be using an autodoc directive so you loose the automatic extraction of docstrings from your Python source code. Depending on where you decide to place .. py:function:: it may be necessary to use :noindex: and :exclude-members: in specific directives - usage shown in the example.

Notice the last example still requires a leading . dot, otherwise Sphinx will prepend the fully qualified name as specified by add_module_names = True.

Two simple example files, bar.some_other_file.py:

"""bar.some_other_file module docstring."""

def some_other_function():
    """some_other_function docstring."""

and _foo.some_file.py:

"""_foo.some_file module docstring."""

def some_function(argument_example="a string"):
    """some_function docstring."""

Using the following .rst to compare both cases:

_foo costum module name
-----------------------

.. automodule:: _foo.some_file
    :members:
    :undoc-members:
    :exclude-members: some_function

    .. autofunction:: some_function

    .. py:function:: .some_function(argument_example="a string")
        :noindex:

        Example without any module name.

bar costum module name
----------------------

.. automodule:: bar.some_other_file
    :members:
    :undoc-members:
    :exclude-members: some_other_function

    .. autofunction:: some_other_function

    .. py:function:: bar.some_other_file.some_function(argument_example="a string")
        :noindex:

        Example with a different qualified name.

Gives the following result:

enter image description here

How can I change `add_module_names` to `False` for specific modules?

1 Answers1