Sphinx autosummary link to imported member documentation

Question

I'm trying to document a somewhat complex python package it has several private submodules

i.e.

package
 +-- __init__.py "Package Initialization"
 +-- _info.py "Package Info"
 +-- _core.py "Packages Core members"
 +-- _extra1.py "Package Extra members group 1"

then in __init__.py I have:

from package._info import __authors__, __copyright__, __license__, \
                          __contact__, __version__, __title__, __desc__

from package._core import funcA, funcB, classA, classB

try:
    from package._extra1 import funcE1A, funcE1B, funcE1C
except ImportError:
    _extra1_requirement = "Requires external_package>=x.y"

    def funcE1A(*args, **kwargs):
        raise NotImplementedError(_extra1_requirement)

    def funcE1B(*args, **kwargs):
        raise NotImplementedError(_extra1_requirement)

    def funcE1C(*args, **kwargs):
        raise NotImplementedError(_extra1_requirement)

so that all the public members are available in the package namespace however when I use autosummary in sphinx to document my package i.e.

.. automodule:: package

Core Functions
--------------
.. autosummary::
    :toctree: reference/

    funcA
    funcB

Core Classes
------------
.. autosummary::
    :toctree: reference/

    classA
    classB

Extra 1 Functions
-----------------
.. autosummary::
    :toctree: reference/

    funcE1A
    funcE1B
    funcE1C

it generates the autodoc files for reference/package.member along with the summary table however it fails to create links from the summary table to the main documentation page for each member if I change my documentation to

.. automodule:: package

Core Functions
--------------
.. currentmodule:: package._core
.. autosummary::
    :toctree: reference/

    funcA
    funcB

Core Classes
------------
.. currentmodule:: package._core
.. autosummary::
    :toctree: reference/

    classA
    classB

Extra 1 Functions
-----------------
.. currentmodule:: package._extra1
.. autosummary::
    :toctree: reference/

    funcE1A
    funcE1B
    funcE1C

It generate the links to the documentation pages however those pages are now named as reference/package.private_submodule.member rather than reference/package.member

I want to keep the main documentation pages as reference/package.member and have autosummary generate links to these pages. However I haven't been able to find anything to help despite multiple search and going through the documentation https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html

score 1 · Answer 1 · answered Mar 27 '19 at 11:52

I found the problem

I had gone through renaming the autogenerated files when I was taking out the private submodule, autosummary had generated this files with the line:

.. currentmodule:: package.submodule

this line is the source of the error, as the refactoring required it to be changed to :

.. currentmodule:: package

After discovering this I renamed a few files and rerun the build, the new files generated by autosummary were linked correctly.

Sphinx autosummary link to imported member documentation

1 Answers1