Pragmatism in the real world

rst2html does not support :startinline:

I’m currently writing some documentation in Restructured Text that I’m targeting at HTML and PDF using rst2html and rst2pdf.

For syntax highlighting, both rst2html and rst2pdf use Pygments, however rst2html doesn’t support any Pygments options.

So a typical PHP snippet in rst targeting rst2pdf, would be written as:

.. code-block: php
    :startinline: true

    $this = str_replace('foo', 'bar', $that);

The startinline Pygments option is to allow it to highlight the snippet, even though the opening <?php is missing.

If you run rst2html, you get this error:

(ERROR/3) Error in "code-block" directive: unknown option: "startinline".


To remove the error, I’ve simply run my rst file through see first, so I have a script that does this:


sed '/startinline/d' ${1}.rst > temp.rst --syntax-highlight=short --stylesheet=syntax.css temp.rst > ${1}.html
rm temp.rst

The sed command removes any lines that contain the word startinline and obviously, this means that the HTML version doesn’t syntax highlight the snippet, but at least it doesn’t generate an error!