如何将 Sphinx 自定义指令内容解析为 docutil 节点

Question

我正在尝试创建一个名为 LicenceDirective 的自定义指令，它看起来像：

.. licence: Some Software 3.0
   :url: https://SomeSoftware.com/downloads
   :path: /licence_file

   CONTENT

此类指令的 HTML 输出将是：

<h1 id="some-software-3-0">Some Software 3.0</h1>
<p><a href="https://SomeSoftware.com/downloads">Download page</a></p>
RST_PARSED(CONTENT)
<pre>{{content of licence_file}}</pre>

CONTENT 可以是任何有效的 RST 内容，包括格式、列表、headers、...。所以我需要将它 as-is 和 return 结果节点解析为 return 它们以及我自己来自 LicenceDirective::run() 的节点。有办法吗？

Answer 1

我找到了使用 nested_parse 的解决方案，并在此处提到：

https://www.sphinx-doc.org/en/master/extdev/markupapi.html#parsing-directive-content-as-rest

如何将 Sphinx 自定义指令内容解析为 docutil 节点

How to parse Sphinx custom directive content to docutil nodes

python

restructuredtext

docutils

python-sphinx