Search code examples
pythonpython-sphinxautodoc

Function appears two times in Sphinx autodoc generated documentation

Background information

I generate documentation from docstrings via Sphinx autodoc. There is a function mypackage.mypackage.foo() located in source file mypackage/mypackage.py. It is imported implicite in the __init__.py, so the user can it use as mypackage.foo().

I do manipulate Sphinx autodoc that it generates the docu for foo() respecting they way it is imported. This works.

The problem

The docu about foo() is generated twice; once as mypackage.foo() and once as mypackage.mypackage.foo().

enter image description here

Details

This is the structure of the project:

mypackage
├── a.py
├── __init__.py
└── mypackage.py

The __init__.py does the import and then manipulates the __all__ variable:

from .mypackage import *
__all__ = ['foo']  # for alternative see: https://stackoverflow.com/a/66996523/4865723

And the mypackage/mypackage.py defines foo().

Because of that I can do things like that:

import mypackage
mypackage.foo()

Related questions and answers

Here are questions and answers that took me to the current "part solution". Where mypackage.foo() appears as expected in the documentation but mypackage.mypackage.foo() does not disappear.

Solution

  • @mzjn gave me the right direction. He is correct that there are two automodule directives. So the goal is to make sphinx-apidoc (which generates the directives) ignore mypackage/mypackage.py.

    For that make it a "private module" with modyfing it's filename starting with an underscore (_).

    The resulting project structure:

    mypackage
├── a.py
├── __init__.py
└── _mypackage.py

    And the import in __init__.py need to modified to from ._mypackage import *.