我正在考虑将我的文档从 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这样的扩展，但我希望有一个更简单的方法。
要使星号出现在“我的部分”下方，您需要至少有一个空行将“我的部分”与“|H1|”分隔开。 Sphinx/docutils 中的空格有意义，并且分隔的内容被解释为两个段落而不是内联文本。
.. |H1| replace:: `*****************************************************`
My section
|H1|
要显示反引号，请使用反斜杠字符
\.. |H1| replace:: \`*****************************************************\`
My section
|H1|
raw编辑
这将创建一个部分。
My section
==========
两个段落之间的空行将生成段落，如上所述。
这种类型的别名最好在自定义预处理器中完成（也许已经有一个 Sphinx 扩展）。