0

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.

mzjn
  • 48,958
  • 13
  • 128
  • 248
buhtz
  • 10,774
  • 18
  • 76
  • 149
  • 1
    I suppose that there are two `automodule` directives at play here. You need to remove one of them. – mzjn Mar 05 '22 at 15:45
  • Of course they are because `sphinx-apidoc` generates them this way. I can not edit the rst-files because my edits are overwritten everytime I call `sphinx-apidoc`. – buhtz Mar 05 '22 at 19:26
  • 1
    You don't necessarily have to run sphinx-apidoc over and over again. You can run it once or twice, edit the generated RST files and then add these files to version control. See https://stackoverflow.com/q/28481471/407651. – mzjn Mar 06 '22 at 08:42

1 Answers1

0

@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 *.

buhtz
  • 10,774
  • 18
  • 76
  • 149