Объединение документации Sphinx из нескольких подпроектов: обработка индексов, синхронизация конфигурации и т. Д. - PullRequest
Новая
       17

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

22 голосов
/ 13 июня 2011

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

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

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

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

Ответы [ 2 ]

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

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

    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>

    Я почти уверен, что эта схема сработает, но я сам пока не проверял ее.

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

0 голосов
/ 15 февраля 2016

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

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

Обратите внимание, что в отличие от структуры каталогов, представленной @ 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
...