Блог

Я пытаюсь задокументировать несколько сложный пакет 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 и заставить autosummary генерировать ссылки на эти страницы. Однако я не смог найти ничего, что могло бы помочь, несмотря на многократный поиск и просмотр документацииhttps://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html

Я обнаружил проблему

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

 .. currentmodule:: package.submodule
  

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

 .. currentmodule:: package
  

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