Search code examples
pythonpython-sphinxrestructuredtextdocutils

How to parse Sphinx custom directive content to docutil nodes

I'm trying to create a custom directive called LicenceDirective which looks like it:

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

   CONTENT

The HTML output of such directive would be:

<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 can be any valid RST content, including formatting, lists, headers, ... . So i need to parse it as-is and return the resulting nodes to return them along with my own nodes from LicenceDirective::run(). Is there a way to do that?

Solution

  • I found the solution using nested_parse, and mentioned here:

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