При создании документации с использованием Sphinx я хотел бы иметь возможность генерировать две версии моей документации: одну, включая все, и одну только с определенным набором страниц. Какой лучший способ достичь этого?
Я мог бы написать сборку script, которая перемещает файлы для достижения этого, но было бы очень приятно, если бы был способ сообщить sphinx исключить или включить определенные документы во время конкретной сборки.
Директивы only и ifconfig могут использоваться для применения условий на страницах.
Кажется, не существует простого способа использовать условия, чтобы полностью исключить целые страницы (файлы .rst).
Следующее (в index.rst) исключает ссылку на doc2.html в toctree в index.html при создании вывода HTML:
.. toctree::
doc1.rst
.. only:: latex
.. toctree::
doc2.rst
Но это на самом деле не работает. Файл doc2.html все еще генерируется, и он доступен по ссылке "Следующая тема", когда doc1.html является текущей темой.
Возможно, мой ответ приходит с некоторым опозданием, но мне удалось сделать это с помощью Sphinx с помощью шаблонов исключений в файле конфигурации.
Моя документация частично для пользователей и частично для администраторов.
У некоторых страниц есть имена файлов, которые содержат слово admin, и, как и вы, я хотел создать две версии: одну со всем (документы администратора) и одну со всеми исключенными страницами администратора (документы пользователя).
Чтобы исключить все страницы "admin" во всех подпапках, вы должны добавить эту строку в конфигурационный файл conf.py:
exclude_patterns = ['**/*admin*']
Это была легкая часть.
Моя проблема заключалась в том, что я не знал, как запустить сборку два раза, один с и без шаблонов исключения без использования двух разных конфигурационных файлов.
Я не нашел решения самостоятельно, поэтому я задал вопрос здесь на SO и получил ответ:
Таким образом, у меня есть этот шаблон исключения в моем файле конфигурации:
exclude_patterns = ['**/*admin*']
if tags.has('adminmode'):
exclude_patterns = []
Теперь я могу запустить сборку, не пропуская ничего, за исключением файлов "admin":
make clean
make html
⇒ это моя пользовательская документация
... и я могу установить тег "adminmode", который ничего не исключает:
(Синтаксис командной строки Windows)
set SPHINXOPTS=-t adminmode
make clean
make html
⇒ это моя административная документация.
Бонус:
Я могу использовать один и тот же тег, чтобы игнорировать определенный контент на странице, включая контент на основе тегов.
Пример:
regular documentation
=====================
This paragraph and its headline will always be visible.
.. only:: adminmode
secret admin stuff
------------------
This paragraph will be visible in the admin docs only.
This will (again) always be visible.
Как насчет sphinx.ext.ifconfig? Вы устанавливаете значения конфигурации в своем файле conf.py. Поскольку это обычный файл Python, вы можете сделать критерии включения умными и автоматическими, если вам нужно.