Как условно включить файл в toctree Sphinx?

Я хотел бы включить один из моих файлов в оглавление Sphinx только тогда, когда установлен определенный тег, однако очевидный подход не работает:

.. toctree::
   :maxdepth: 5

   index
   core
   utils
   oec
   plotting

   install
   news

   glossary

   .. only:: private_version

      todo

Есть ли простой способ сделать это?


python conditional-statements python-sphinx toctree
person orome    schedule 02.02.2014    source источник

Ответы (1)


arrow_upward
3
arrow_downward

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

Чтобы добиться успеха, мне пришлось написать собственный плагин (его можно найти здесь).

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

.. meta::
    :scope: private_version

public-sample.rst (ничего особенного)

Title
=====

A public content

private-sample.rst

.. meta::
    :scope: private_version

Title
=====

A private content

index.rst

.. toctree::
    :maxdepth: 3

    public-sample.rst
    private-sample.rst

Как вы можете видеть, в toctree есть обе ссылки, но плагин удалит private-sample.rst во время компиляции, если вы не используете тег private.

Итак, используя

sphinx-build ... -t private_version ...

Будет генерировать toctree как:

  • общественно-sample.rst
  • частный образец.rst

но если вы строите с

sphinx-build ... -t other ...

or

sphinx-build ...

toctree будет выглядеть так

  • общественно-sample.rst

Мой плагин не на 100% идеален, но я всего лишь небольшой фрагмент кода, который легко понять, поэтому вы можете редактировать, как хотите :)

Знайте ограничения:

ограничение:

  • Директива .. meta:: :scope: должна быть в начале файла (без строки перед)
  • Директива .. meta:: :scope: должна соответствовать регулярному выражению ^.. meta::\s+:scope: ([a-zA-Z0-9_-]+)
  • Директива .. meta:: :scope: может управлять несколькими тегами, но вы можете легко обновить плагин для своих нужд.
  • Плагин отклоняет исходное использование директивы meta docutils.sourceforge.net/docs/ref/rst/directives.html#meta
person Kakawait    schedule 25.02.2014
comment
Я думаю, вам следует предоставить ссылку на docutils.sourceforge.net/docs/ ref/rst/directives.html#meta и объясните, что вы злоупотребляете директивой meta. - person mzjn; 26.02.2014
comment
Вы случайно не знаете, как избавиться от всех сообщений ПРЕДУПРЕЖДЕНИЕ: toctree содержит ссылку на несуществующий документ u'private-sample.rst'? Я использую ваш скрипт (спасибо!!), чтобы исключить многие файлы, и я получаю много таких предупреждений. - person calys; 21.10.2015
comment
@calys поместил :orphan: в начало каждого файла, чтобы предупреждение не отображалось. - person 0leg; 22.05.2019