Need a different module name when using Python's Sphinx automodule directive

Question

I have a file layout that looks like:

/my_module
    __init__.py
    submodule1.py
    submodule2.py

I use Sphinx's automodule directive like:

.. automodule:: my_module.submodule1

It produces documents that say my command name is something like: my_module.submodule1.my_function. But my __init__ pulls submodule1 into the my_module namespace. So what I really want is for the documentation to say my_module.my_function instead. Leave out the submodule1, since that's not what users are going to use.

Is there a way to do this?

Answer 1

Not exactly, but you can get close. There is the ~ (tilde) in standard cross-referencing syntax.

If you prefix the content with ~, the link text will only be the last component of the target. For example,

:py:meth:`~Queue.Queue.get`

will refer to Queue.Queue.get but only display get as the link text. This does not work with all cross-reference roles, but is domain specific.

You might be able to use substitutions or the raw directive, but that would bypass the advantage of using autodoc and its directives.