22

I have a Python package that I am attempting to document with sphinx-autodoc. My python package has an __init__.py file that imports a class out from a submodule to make it accessible at the package level.

from a.b.c.d import _Foo as Foo

__all__ = ["Foo"]

If I do this, my (html) documentation is as follows:

a.b.c package

Submodules

a.b.c.d module

[snip documentation of irrelevant public classes within the a.b.c.d module]

Module contents

The c module.

a.b.c.Foo

alias of _Foo

Not super useful since _Foo is (rightly) undocumented as it is a private class within the a.b.c.d submodule.

I can add the following to my conf.py which ensures that the private class definition in the module is documented.

def skip(app, what, name, obj, skip, options):
    if name == "_Foo":
        return False
    return skip

Other alternative, but not great things I've tried:

  1. Rename a.b.c.d._Foo to a.b.c.d.Foo (and then update the import to from a.b.c.d import Foo) -- but then I get the class documented twice, once under the a.b.c.d module heading, and once again under the Module contents heading.
  2. Renaming a.b.c.d.Foo to a.b.c.d.MyFoo and then importing (from a.b.c.d import MyFoo as Foo) results in MyFoo being documented, and Foo being listed as an alias of MyFoo.

Ideally I'd like the private definition to remain undocumented, but to have the version imported into the package fully documented. Does anyone know how I might achieve this?

Community
  • 1
  • 1
Saff
  • 501
  • 3
  • 13

2 Answers2

4

Sphinx uses the __name__ and __module__ members of the class, and the __module__ member of the owner of the class to figure out if it is an alias or the real thing. You can trick Sphinx in thinking that your imported class is the real one by setting these members explicitly.

from a.b.c.d import _Foo as Foo
Foo.__module__ = __name__
Foo.__name__ = 'Foo'
barjak
  • 10,842
  • 3
  • 33
  • 47
  • If you do this then you break `inspect.getsource(Foo)` – Eric Mar 27 '20 at 12:25
  • 5
    Do this in the `setup` function in `conf.py` and then you won't mess with anything in the original source code. For example: https://github.com/slundberg/shap/blob/6af9e1008702fb0fab939bf2154bbf93dfe84a16/docs/conf.py#L380-L394 – slund Dec 12 '20 at 01:12
1

Using the members directive you can show all members except those that start with '_'. You can leave _Foo undocumented in a.b.c.d and document it as Foo in a.b.c. I would import _Foo as from a.b.c.d import _Foo and then add whatever documentation like:

Foo = _Foo
''' blah blah blah '''

If, for some reason, you don't want _Foo in a.b.c's namespace, then you can also do:

from a.b.c.d import _Foo as Foo
Foo = Foo
''' blah blah blah '''
markw
  • 620
  • 3
  • 14