Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Sphinx inline code highlight

Tags:

I use Sphinx to make a website that contains code samples. I'm successful using the .. code-block directive to get syntax highlighting. But I can't get inline syntax highlighting using this code:

.. role:: bash(code)
   :language: bash

Test inline: :bash:`export FOO="bar"`.

.. code-block:: bash

    export FOO="bar"

which produces this output i.e. inline code not highlighted while block code is:

result

Problem to me is that the generated HTML for inline code contains long class names while it does not for code blocks. Here is the output HTML (indented for readability):

<p>Test inline:
    <tt class="code bash docutils literal">
        <span class="name builtin">
            <span class="pre">export</span>
        </span>
        <span class="name variable">
            <span class="pre">FOO</span>
        </span>
        <span class="operator">
            <span class="pre">=</span>
        </span>
        <span class="literal string double">
            <span class="pre">&quot;bar&quot;</span>
        </span>
    </tt>.
</p>


<p>Test code-block:</p>
<div class="highlight-bash">
    <div class="highlight">
        <pre>
            <span class="nb">export </span>
            <span class="nv">FOO</span>
            <span class="o">=</span>
            <span class="s2">&quot;bar&quot;</span>
        </pre>
    </div>
</div>

Any help would be very much appreciated.

like image 268
ben Avatar asked Feb 05 '14 23:02

ben


People also ask

How do you use a sphinx code block?

Literal code blocks (ref) are introduced by ending a paragraph with the special marker :: . The literal block must be indented (and, like all paragraphs, separated from the surrounding ones by blank lines): This is a normal text paragraph.

What is inline code?

Inline code refers to any lines of code that are added in the body of a program. It can be any type of code written in any programming language. The inline code executes independently and is usually executed under some condition by the primary program.

What is RST Sphinx?

RST stands for ReStructured Text. It is the standard markup language used for documenting python packages. Sphinx is the Python package that generates an html website from RST files, and it is what we are using to generate this site.


2 Answers

syntax_highlight is an ordinary docutils setting, which can be set in docutils.conf. This file is respected by Sphinx too, if placed in the Sphinx's configuration directory (where conf.py resides):

[restructuredtext parser]
syntax_highlight = short

This is much better than patching docutils or sphinx code or creating a long name CSS file.

like image 192
Sebastian Schrader Avatar answered Sep 28 '22 02:09

Sebastian Schrader


Found a better (sphinx-only) solution: in sphinx/builders/html.py find a line

from docutils.core import Publisher

and change it to:

from docutils.core import Publisher
def process_programmatic_settings(self, settings_spec,
                                  settings_overrides,
                                  config_section):
    if self.settings is None:
        defaults = (settings_overrides or {}).copy()
        # Propagate exceptions by default when used programmatically:
        defaults.setdefault('traceback', True)
        defaults.setdefault('syntax_highlight', 'short') # ADDED THIS LINE
        self.get_settings(settings_spec=settings_spec,
                          config_section=config_section,
                          **defaults)
Publisher.process_programmatic_settings = process_programmatic_settings

This solution is better then previous ones: since it doesn't double the amount of css rules, and doesn't modify docutils.

Still, ideal solution would only change conf.py. So there's a plenty space for improvement.

like image 23
Adobe Avatar answered Sep 28 '22 02:09

Adobe