Автосуммирующая ссылка Sphinx на импортированную документацию - PullRequest
Новая
       12

Автосуммирующая ссылка Sphinx на импортированную документацию

0 голосов
/ 27 марта 2019

Я пытаюсь задокументировать довольно сложный пакет python, в котором есть несколько личных подмодулей

, т. Е. 

package
 +-- __init__.py "Package Initialization"
 +-- _info.py "Package Info"
 +-- _core.py "Packages Core members"
 +-- _extra1.py "Package Extra members group 1"

, затем в __init__.py У меня есть: 

from package._info import __authors__, __copyright__, __license__, \
                          __contact__, __version__, __title__, __desc__

from package._core import funcA, funcB, classA, classB

try:
    from package._extra1 import funcE1A, funcE1B, funcE1C
except ImportError:
    _extra1_requirement = "Requires external_package>=x.y"

    def funcE1A(*args, **kwargs):
        raise NotImplementedError(_extra1_requirement)

    def funcE1B(*args, **kwargs):
        raise NotImplementedError(_extra1_requirement)

    def funcE1C(*args, **kwargs):
        raise NotImplementedError(_extra1_requirement)

, так что все открытые члены доступны в пространстве имен package, однако, когда я использую autosummary в sphinx для документирования своего пакета, т.е. 

.. automodule:: package

Core Functions
--------------
.. autosummary::
    :toctree: reference/

    funcA
    funcB

Core Classes
------------
.. autosummary::
    :toctree: reference/

    classA
    classB

Extra 1 Functions
-----------------
.. autosummary::
    :toctree: reference/

    funcE1A
    funcE1B
    funcE1C

, он генерирует файлы autodoc для reference/package.member вместе со сводкойоднако таблица не может создать ссылки из сводной таблицы на главную страницу документации для каждого участника, если я изменю свою документацию на 

.. automodule:: package

Core Functions
--------------
.. currentmodule:: package._core
.. autosummary::
    :toctree: reference/

    funcA
    funcB

Core Classes
------------
.. currentmodule:: package._core
.. autosummary::
    :toctree: reference/

    classA
    classB

Extra 1 Functions
-----------------
.. currentmodule:: package._extra1
.. autosummary::
    :toctree: reference/

    funcE1A
    funcE1B
    funcE1C

Она генерирует ссылки на страницы документации, однако эти страницы теперь называются reference/package.private_submodule.member вместо reference/package.member

Я хочу сохранить основные страницы документации как reference/package.member и автоматически генерировать ссылки на эти страницы.Однако я не смог найти ничего, что могло бы помочь, несмотря на многократный поиск и просмотр документации https://www.sphinx -doc.org / ru / master / использовании / extensions / autosummary.html

1 Ответ

0 голосов
/ 27 марта 2019

Я нашел проблему

Я переименовал автоматически сгенерированные файлы, когда вынимал закрытый подмодуль, autosummary генерировал эти файлы со строкой: 

.. currentmodule:: package.submodule

эта строка является источником ошибки, так как рефакторинг потребовал ее изменить на: 

.. currentmodule:: package

Обнаружив это, я переименовал несколько файлов и перезапустил сборку, новые файлы, сгенерированные автосуммаркой, были правильно связаны.

...