Cómo hacer que Sphinx respete la importación de clases en un paquete con __init__.py

Tengo un paquete

  • foo
    • foo.py
    • bar.py
    • __init__.py

foo.py tiene una clase Foo. En __init__.py importo la clase Foo para que los usuarios puedan hacer:

from foo import Foo 

Sphinx documenta correctamente a Foo como foo.foo.Foo, lo cual es correcto pero confuso para los usuarios. ¿Cómo consigo que Sphinx lo documente como foo.Foo?

También es importante obtener la documentación general del módulo asociada con el módulo correcto.

Esfinge documenta algo llamado:

 ..module:: module.name 

pero cuando lo uso en el primer comentario en un archivo foo.py , el documento todavía se atribuye a foo.foo .

El valor del atributo __module__ es el nombre del módulo en el que se definió una clase / función / método (consulte https://docs.python.org/2.7/reference/datamodel.html ). El atributo se puede escribir, por lo que se puede redefinir en __init__.py:

 Foo.__module__ = "foo" 

Ahora, si usa .. automodule:: foo , el nombre calificado de la clase Foo se mostrará como foo.Foo en la documentación del módulo generado.


Como alternativa a __module__ fiddling, puede usar autoclass lugar de automodule .

.. autoclass:: foo.Foo producirá la salida deseada.