如何在代码块中包含内部引用？

Question

在我的 Sphinx .rst 文档中，我有一个代码块，其中包含使用 UNIX tree 命令的产品结构树视图：

  |── parent
  |   |── child
  |       |── grandchild

它位于代码块中，以便 Sphinx 保留空格。

我希望读者能够单击每个节点以跟随 internal hyperlink 到文档中描述该节点的部分。但是，在代码块中添加 :ref: 不起作用（见下文）。有谁知道如何做到这一点？

这不起作用：

.. _parent:

Parent
------
Blah blah

.. _child:

Child
-----
Blah blah

.. _grandchild:

Grandchild
----------
Blah blah

然后...:[=16=]

|── :ref:`parent`
|   |── :ref:`child`
|       |── :ref:`grandchild`

Answer 1

您可以使用 parsed-literal 指令：

.. parsed-literal:: 

   |── :ref:`parent`
   |   |── :ref:`child`
   |       |── :ref:`grandchild`

这有效，但有警告消息说 "WARNING: Inline substitution_reference start-string without end-string."

竖线被解释为 substitution references 的一部分。警告会随着一些转义而消失：

.. parsed-literal:: 

   \|── :ref:`parent`
   |   \|── :ref:`child`
   |       \|── :ref:`grandchild`

Answer 2

.. code-block:: 用于文字代码，除语法突出显示外不进行解析。

相反，您可以使用 CSS class my-special-class 将样式应用于树，并编写 CSS 类似于 HTML 的 <pre> 或 <code>。您还需要将 | 转义为 \|，因为 reST 会尝试将 | 解析为替换。

休息：

.. rst-class:: my-special-class

\|── :ref:`parent`
\|   \|── :ref:`child`
\|       \|── :ref:`grandchild`

CSS:

.my-special-class {
    font-family: monospace;
    white-space: pre;
}

How to include an internal reference in a code block?