Как я могу документировать классы без имени модуля?

Я пытаюсь документировать пакет python с sphinx и успешно сгенерировал html файлы. Пакет, который я документирую, состоит из набора файлов *.py, большинство из которых содержат один класс с несколькими файлами, являющимися подлинными модулями с определенными функциями. Мне не нужно раскрывать тот факт, что каждый класс находится в модуле, поэтому я добавил подходящие операторы from в файле __init__.py, например.

from base import Base

чтобы пользователь мог использовать команду import pkg и не должен указывать модуль, который содержит класс:

import pkg
class MyBase(pkg.Base):  # instead of pkg.base.Base ...
...

Проблема заключается в том, что сфинкс настаивает на документировании класса как pkg.base.Base. Я попытался установить add_module_names = False в conf.py. Однако это приводит к тому, что сфинкс показывает класс как просто Base вместо pkg.Base. Кроме того, это также разрушает документацию нескольких файлов *.py, которые являются модулями.

Как сделать sphinx показать класс как pkg.Base? И как я могу установить директиву add_module_names выборочно для каждого файла *.py?

Ответ 1

Вот способ выполнить то, что OP просит:

Добавьте список __all__ в pkg/__init__.py:

from base import Base    # Or use 'from base import *'

__all__ = ["Base"]

Используйте .. automodule:: pkg в файле.rst.

Теперь Sphinx выводит документацию, где имя класса отображается как pkg.Base вместо pkg.base.Base.

Ответ 2

Короткий ответ: Вы не должны. Просто укажите sphinx в каталог вашего кода. Сфинкс документирует код и показывает модуль hirarchy. Как модуль, наконец, будет импортирован, исключительно в руке разработчика, но не несет ответственности за инструмент документации.