可以使用 `ifconfig` 块 (reStructuredText) 有条件地定义目标

Question

是否可以在 reStructuredText 文件中使用ifconfig 有条件地定义target？

我在我的 sphinx conf.py 文件中设置了一个变量，我想用它来有条件地确定文档中目标的 URI：

def setup(app):

    argv = ' '.join(sys.argv)
    if '-b html' in argv:
        app.add_config_value('buildername', 'html', 'env')
    else:
        app.add_config_value('buildername', 'not-html', 'env')

而我的index.rst文件内容如下：

test link to target1_

.. ifconfig:: buildername == 'html'

  .. _target1: https://example.com/a

上述工作按预期工作，“target1”成为example.com/a的超链接

但如果我想实际定义 target1 以根据 buildername 配置变量的值有条件地设置为两个选项之一，那么我有

test link to target1_

.. ifconfig:: buildername == 'html'

  .. _target1: https://example.com/a

.. ifconfig:: buildername != 'html'

  .. _target1: https://example.com/b

上述输出不仅对example.com/b 不起作用，而且它破坏了第一个链接并且target1 现在指向任何内容（实际上是#id3）。

此外，我在sphinx-build 输出中收到以下警告

user@host:~$ make clean && sphinx-build -b html . _build/html/
...
reading sources... [100%] support                                               
.../index.rst:16: WARNING: Duplicate explicit target name: "target1".
.../index.rst:8: WARNING: Duplicate target name, cannot be used as a unique reference: "target1".
...

是否可以在 .rst 文件中定义相同的目标两次，这样每个定义都包含在 ifconfig 指令中？

Answer 1

不幸的是，我不认为你想要的是可能的。您可以抑制警告（这可能不是一个好主意），或者您可以添加更多标记以通过目标和链接之间的一对一关系来避免它们。

.. ifconfig:: buildername == 'html'

    test link to target1_

.. ifconfig:: buildername == 'html'

    .. _target1: https://example.com/a

.. ifconfig:: buildername != 'html'

    test link to target2_

.. ifconfig:: buildername != 'html'

    .. _target2: https://example.com/b