如何在Sphinx“ toctree”中有条件地包含文件？ [英] How do I conditionally include a file in a Sphinx 'toctree'?

问题描述

仅当设置了特定标签时，我才想在Sphinx TOC中包含一个文件，但是显而易见的方法失败了：

I would like to include one of my files in my Sphinx TOC only when a certain tag is set, however the obvious approach fails:

.. toctree::
   :maxdepth: 5

   index
   core
   utils
   oec
   plotting

   install
   news

   glossary

   .. only:: private_version

      todo

有没有简单的方法可以做到这一点？

Is there a simple way to accomplish this?

推荐答案

过去，我需要能够从同一个源文件中编译两个文档：一个公共文件和一个私有文件。

In a past I had a need to be able to compile two documentations from the same source file: a public and a private.

要获得成功，我必须编写我自己的插件（您可以在此处）。

To succeed I had to write my own plugin (that you can find here).

当我只有私人文档中的文件时，只需在文件顶部添加以下指令（强制性）

When I have a file to be only on private documentation I just add this following directive on the top of the file (mandatory)

.. 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

As you can see on toctree there is the both reference, but the plugin will remove the private-sample.rst during compilation if you'r not building with tag private

进行编译，则使用

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

将生成 toctree ，例如：

• public-sample.rst


• pr ivate-sample.rst

但是如果您使用

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

或

sphinx-build ...

toctree 看起来像

• public- sample.rst

我的插件不是100％完美，但我只是一小段易于理解的代码，因此您可以像您想要：）

My plugin is not 100% perfect but I just a small piece of code a easy to understand so you can edit like you want :)

了解限制：

限制：

• 指令.. meta ::：scope：必须放在文件的顶部（前无行）


• 指令.. meta ::：scope：必须与regexp ^ .. meta :: \s +：scope：（[a-zA-Z0-9 _-] +）


• 指令.. meta ::：scope：可以管理多个标签，但是您可以根据需要轻松更新插件


• 插件偏离了 meta 指令docutils.sourceforge.net/docs/ref/rst/ indicators.html＃meta



• The directive .. meta:: :scope: must be place at the top of the file (no line before)
• The directive .. meta:: :scope: must match the regexp ^.. meta::\s+:scope: ([a-zA-Z0-9_-]+)
• The directive .. meta:: :scope: can manage multiple tag but you can easily update the plugin for your needs
• Plugin deviate the original use of meta directive docutils.sourceforge.net/docs/ref/rst/directives.html#meta

这篇关于如何在Sphinx“ toctree”中有条件地包含文件？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！