如何在文档中多次引用文本块？

Question

我正在编写大量 Sphinx/RestructuredText，其中包括使用 PlantUML 的序列图。我有很多要重用的文本，所以为了让事情更整洁，我创建了一个 definitions.iuml 文件。在这个文件中，我可以创建命名文本引用（通过 !startsub/!endsub 块），允许我在几个不同的序列图中引用它们。在源位置更改一次，它们都会更改。完美。

我的问题是如何在序列图之外使用这些引用？我在 .rst 文件中使用完全相同的代码 (!includesub ../defintions.iuml!NAMED-REFERENCE)，并且当我制作 docx/pdf 时，我看到了那个链接，我没有看到它引用的文本。更糟糕的是，谷歌对此没有任何文档或搜索结果。 includesub、startsub、endsub +sphinx 的查询返回什么都没有。

帮助我obiwan kenobi。

Answer 1

我找到了答案，这只会导致更多问题哈哈。无论如何，一次只做一件事：

1. 要在文本文档中创建参考变量，请在 Conf.py 文件中使用 rst_prolog 或 rst_epilog。我不知道为什么有 2 个命令可以达到相同的目的。

    rst_prolog = """
    .. |Variable1| replace:: Monday
    .. |Variable2| replace:: Tuesday 
    """
   

现在每当你写 |Variable1|在您的文本中，文档将生成星期一。

1. 上面的问题是它只适用于简短的单词/短语。您不能将它用于代码块或超过一行的任何内容。在代码块中引用：

• 使用要显示的代码创建一个新的 .rst 文件。最佳做法是创建一个 Code 文件夹并将它们全部放在其中。

• 进一步的最佳做法是停止使用“.. code block::”，而使用“.. parsed-literal::”。输出完全相同，但 parsed-literal 允许您使用 conf.py 变量和 ..codeblock:: 不使用。

• 所以在这个 .rst 文件中，第一行是 .. parsed-literal:: 并且它下面的所有文本都是你要引用的代码

• 在您想要此代码的原始文档中，键入：

    <4 spaces indent>.. include:: <Folder/File.rst>
  

• 生成您的文档，并注意代码现在是如何被引用的。您可以在整个文档中包含此参考。

我将很快创建一个新线程，这一次询问文本正文和序列图如何使用相同的引用。目前，所有文本都需要一个引用，所有序列都需要另一个引用，现在我们有双重更新。不理想