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?

Answer 1

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: