在Sphinx中添加自定义标签

Question

我正在使用 Sphinx 工具进行文档记录，并遇到了一种情况，我只想以一种文件格式公开一条信息。
我遇到了这个链接，它在 only 指令的帮助下解决了类似的问题。

我面临的问题是我想使用带有自定义标签的唯一指令

.. only:: xyz

  ..directive ::
    :maxdepth: 1

    good_stuff

我使用 setup.py 文件进行构建，并运行 BuildDoc.run(self) 来生成 html 文件。我想以某种方式在 setup.py 文件中传递这个自定义标签。我尝试这样做，但似乎我们无法从 setup.py 文件中访问标签对象。

 def run(self):
    self.builder = 'html'
    *self.tags.add(xyz)*
    BuildDoc.run(self)
    self.zip("html.zip")

如果我在conf.py文件中添加tags.add('xyz')，它总是会暴露附加信息，我想要做的是有条件地在我的setup.py文件中添加这个标签。
我假设 make 命令通过将标签信息传递到 conf.py 文件来执行类似的操作，但我不确定它是如何工作的。

Answer 1

sphinx-build 命令接受

-t

选项，它允许您指定一个可以在

only

条件下使用的标签。

来自

sphinx-build --help

：

    -t TAG            define tag: include "only" blocks with TAG

所以使用类似的东西：

sphinx-build -t xyz

将允许您使用

.. only:: xyz

条件内联。

---

在我看来，如果你想在 setup.py 文件中有条件地应用标签，你必须自己编写逻辑来确定是否应该包含

self.tags.add('xyz')

。

Answer 2

要使用标签，请在您的

setup

中定义函数

conf.py

。

示例：获取环境变量

IS_INTERNAL

以及何时

True

添加标签

internal

:

from os import environ
from typing import Final


def setup(app):
    "Add tag 'internal'"

    IS_INTERNAL: Final[bool] = bool(environ.get("IS_INTERNAL", False))

    if IS_INTERNAL:
        app.tags.add('internal')