Sphinx 别名支持（替换？）

Question

我正在考虑将我的文档从 Doxygen 转移到 Sphinx，并寻找 Doxygen 别名的替代方法。

在 Doxygen 中，我有一个别名，可以将复杂的命令（如表格）替换为更易读的格式（这只是一个示例，我有更复杂和嵌套的示例）：

   table_row2{2}=<tr><td align= center>\1</td><td align= center>\2</td></tr> 

或

 limited_res{1}=The number of supported \1 depends on the specific platform. See the \ref appendixes section" 

它可以像这样在文档中使用：

...
table_h2{ Resource Name, Value }  
table_row2{ MAC Entries , 256}
table_row2{ Ingress Flow , \limited_res { Ingress Flow } }
...

我在 Sphinx 中找到的最接近的东西是替换，但即使是简单的命令替换，我也很难让它工作，如下所示：

.. |H1| replace:: `*****************************************************`

My section
|H1|

H1 ​​要么不编译，要么只打印 '*...*'。

我不确定这是语法问题还是无法解决。我试图避免记住 */ +/ -/ = 中的哪个表示什么，并按嵌套级别命名。这几天记性不太好:)

还有更重要的问题：替换似乎不接受我认为必不可少的参数。

我能想到的另一个选择是写像this这样的扩展，但我希望有一个更简单的方法。

Answer 1

要让星号出现在“我的部分”下方，您需要至少有一个空白行将“我的部分”与“|H1|”分开。 Sphinx/docutils 中的空格是有意义的，分隔的内容被解释为两个段落而不是内联文本。

.. |H1| replace:: `*****************************************************`

My section

|H1|

要显示反引号，请使用反斜杠字符 \ 对其进行转义。

.. |H1| replace:: \`*****************************************************\`

My section

|H1|

如果你想插入 raw，你可以使用raw directive。

编辑

这会创建一个section。

My section
==========

如上所述，两个段落之间的空行将生成段落。