Объединение документации Sphinx из нескольких подпроектов: обработка индексов, настройка синхронизации и т.д.

У нас есть многомодульный проект, задокументированный (превосходным) Sphinx. Наша настройка не похожа на одну описанную в списке рассылки. В целом, отлично работает! Но у нас есть несколько вопросов об этом:

  • Содержание подмодулей будет содержать индексные ссылки. В лучшем случае они свяжутся с неправильными индексами. (В худшем случае это, похоже, вызывает ошибку в Sphinx, но я использую версию devel, чтобы это было разумно). Есть ли способ генерации индексных ссылок только для самого верхнего toctree?

  • Существуют ли лучшие методы для синхронизации конфигурации Sphinx между несколькими проектами? Я мог представить себе что-то взломанное вокруг from common_config import *, но любопытно о других подходах.

  • Пока мы находимся в этом вопросе, вопрос, поднятый в почте списка рассылки (альтернативный symlinking subproject docs?), никогда не отвечал. Это не важно для меня, но это может быть важно для других читателей.

Ответы

Ответ 1

  • Я не уверен, что вы подразумеваете под этим. Ваш проект index выглядит просто отлично. Не могли бы вы пояснить это, пожалуйста?
  • Насколько я понял, from common_config import * - лучший подход для синхронизации конфигурации.

  • Я думаю, что лучший способ сделать это - это что-то вроде следующей структуры каталогов:

    main-project/
 conf.py
 documentation.rst

 sub-project-1/
    conf.py - imports from main-project/conf.py
    documentation.rst

 sub-project-2/
    conf.py - likewise, imports from main-project/conf.py
    documentation.rst

    Затем, чтобы просто упаковать sub-project-1 или sub-project-2, используйте эту команду UNIX:

    sphinx-build main-project/ <output directory> <paths to sub-project docs you want to add>

    Таким образом, будет создана не только основная проектная документация, но и добавленная подпроектная документация, которую вы хотите добавить.

    Чтобы упаковать main-project:

    sphinx-build main-project/ <output directory>

    Я уверен, что эта схема будет работать, но мне еще предстоит проверить ее.

Надеюсь, это поможет!

Ответ 2

Что касается пункта 2 (включая общую конфигурацию), я использую:

В Python 2:

execfile (os.path.abspath("../../common/conf.py"))

В Python 3:

exec (open('../../common/conf.py').read())

Обратите внимание, что в отличие от структуры каталогов, представленной @DangerOnTheRanger, я предпочитаю хранить отдельный каталог для общей документации, поэтому common появляется в указанном выше пути.

Мой общий файл /conf.py - это обычный файл Sphynx. Затем каждая конкретная конфигурация документации включает этот общий файл и при необходимости переопределяет значения, как в этом примере:

import sys
import os

execfile (os.path.abspath("../../common/conf.py"))

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
    'sphinx.ext.viewcode',
]

# If true, 'todo' and 'todoList' produce output, else they produce nothing.
todo_include_todos = True

# If true, links to the reST sources are added to the pages.
html_copy_source = False
html_show_sourcelink = False