Как я могу настроить Sphinx для условного исключения некоторых страниц?

Question

При создании документации с использованием Sphinx я хотел бы иметь возможность создавать две версии моей документации: одну, включающую все, и одну, содержащую только определенный набор страниц.Каков наилучший способ добиться этого?

Я мог бы написать сценарий сборки, который перемещает файлы для достижения этой цели, но было бы очень хорошо, если бы был способ сказать sphinx исключать или включать определенные документы во время определенногостроить.

Answer 1

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

Моя документация частично предназначена для пользователей, а частично для администраторов.
На некоторых страницах есть имена файлов, содержащие слово admin, и, как и вы, я хотел создать две версии: одну со всем (документы администратора) и одну со всеми исключенными страницами администратора (документы пользователя).

Чтобы исключить все страницы "admin" во всех подпапках, вы должны добавить эту строку в файл конфигурации conf.py:

exclude_patterns = ['**/*admin*']

Это была простая часть.

Моя проблема заключалась в том, что я не знал, как запустить сборку два раза, один с и без шаблонов исключения без использования двух разных файлов конфигурации.

Я сам не нашел решения,поэтому я задал вопрос здесь на SO и получил ответ :

• Файл конфигурации представляет собой просто файл Python и может содержать код Python, который будетбыть выполненным на билде.
• Вы можете передать parameters (" tags ") через командную строку, которая может быть запрошена в файле конфигурации.

Итак, у меня есть этот шаблон исключения в моем файле конфигурации:

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.

Answer 2

Директивы only и ifconfig могут использоваться для применения условий на страницах.

Похоже, не существует простого способа использованияусловия для полного исключения целых страниц (файлы .rst).

Следующее (в index.rst) исключает ссылку на doc2.html в toctree в index.html при генерации вывода HTML:

.. toctree::
   doc1.rst

.. only:: latex

   .. toctree::
      doc2.rst

Но это на самом деле не работает.Файл doc2.html все еще создается, и он доступен по ссылке «Следующая тема», когда doc1.html является текущей темой.

Answer 3

Как насчет sphinx.ext.ifconfig ? Вы устанавливаете значения конфигурации в вашем файле conf.py. Поскольку это обычный файл Python, вы можете сделать критерии включения интеллектуальными и автоматическими, если вам нужно.