Перекрестные ссылки Sphinx для унаследованных объектов, импортированные и задокументированные в родительском модуле

Question

Я пытаюсь правильно построить свою документацию по Sphinx и перекрестные ссылки (в том числе из унаследованных отношений) работают правильно.

В моем проекте, у меня ситуация, которая изображена на приведенном ниже примере, который я реплицируется для удобства на this github repo:

$ tree . 
. 
├── a 
│   ├── b 
│   │   └── __init__.py 
│   └── __init__.py 
├── conf.py 
├── index.rst 
└── README.md 

В a.b.__init__, я объявляю классы A и B. B наследует от A. В a.__init__, я импортирую A и B как: from .b import A, B. Причина, по которой я делаю это в своих реальных проектах, - уменьшить пути импорта на модулях, сохраняя при этом реализацию отдельных классов в отдельных файлах.

Затем, в моих файлах сначала я автодок модуль a с .. automodule:: a. Потому что a.b является всего лишь вспомогательным модулем, я не autodoc, так как я не хочу получать повторяющиеся ссылки на одни и те же классы и не путать пользователя с тем, что они должны действительно делать. Я также установил show-inheritance, ожидая, что a.B получит обратную ссылку на a.A.

Если я пытаюсь Сфинкса построить это в режиме нит-разборчивы, я получаю следующее предупреждение:

WARNING: py:class reference target not found: a.b.A 

Если я смотрю на создаваемую документацию для класса B, то я проверить его не правильно связанный с классом A, который просто подтверждает предупреждение выше.

Вопрос: как исправить это?

Answer 1

Sphinx использует значение атрибута __module__ для определения имени модуля, в котором определен класс/функция/метод (см. https://docs.python.org/2/reference/datamodel.html#the-standard-type-hierarchy). Иногда это не то, что вы хотите в документации.

Атрибут доступен для записи. Ваша проблема может быть исправлена ​​путем добавления этой строки в __ init__.py /:.

A.__module__ = "a"