Sphinx alias support (substitutions ?)

0
votes

I'm considering to move my documentation from Doxygen to Sphinx and looking for an alternative for Doxygen alias.

In Doxygen I have an alias that replaces complex command like a table to a more readable format like this (this just an examples and i have more complex and nested ones) :

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

or

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

It can be used in the documentation like this:

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

The closest thing I found in Sphinx is substitutions, but I have trouble to get it to work even for simple command substitutions one like below:

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

My section
|H1|

H1 either does not compile or just print the '*...*'.

I'm not sure if this is a syntax problem or just can't be done. I trying to avoid remembering which of the */ +/ -/ = means what and name it by the level of the nesting. My memory is not very good this days :)

And the more important problem: substitutions does not seem to accept parameters which I found essential.

Another option I can think about is to write extensions like this, but I hope for a more simple method.

1
python-sphinxsubstitutionrestructuredtextsections

1 Answers

0
votes

To get the asterisks to appear below "My section", you need to have at least one blank line separating "My section" from "|H1|". White space in Sphinx/docutils has meaning, and the separated content gets interpreted as two paragraphs instead of inline text.

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

My section

|H1|

To display the backticks, escape them with the backslash character \.

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

My section

|H1|

In case you want to insert raw, you may use the raw directive.

EDIT

This creates a section.

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

A blank line between two paragraphs will generate paragraphs, as noted above.