Creating a sphinx extension involving a directive that takes in arguments

Question

I am relatively new to writing sphinx extensions and would like to create one that takes in a number of keywords that are provided alongside the directive name inside the rst document and replaces it with a block of html.

The predefined list-table directive in docutils allows to do it as following:

.. list-table::

   * - item1

     - item2
   
     - item3

So far, I have only taken a look at the provided helloworld example , which replaces the directive keyword with the string "Hello World".

My idea is to instead return a .. raw:: html tag alongside the html i would like to insert. Is there a good solution to this?

Answer 1

Take a look at sphinx-jinja-ext , a minimal Sphinx directive I wrote recently.

It defines a directive where the 'arguments' you mention are passed as node content:

.. jinja_div:: 

   var1 var2

resulting in this html:

<div class="jinja">
  {{ var1 var2 }}
</div>

It should be simple to adaptjinja.py in that project to your requirements.

In general, it helps to be aware that rST gets mapped to a docutils doctree first, which is then translated to HTML.