Styling of generated code/markup via CSS/pygments

[thaxy]

I know the following is a bit general and not tightly related to this repo but maybe you can make the following use case a bit more clearer for new users like me

Could you add an explanation to the documentation how to apply styles for the (rst) generated markup?
I am a bit lost here because pygments seems to abbreviate the classes like kn or nn see: http://pygments.org/docs/styles/#builtin-styles
But instead, I get something like below. I saw that the unit test covers this with long class names too but I wonder why.

.. code:: python

    import os

    env_hi = os.env('hi')
    print(env_hi)

.. end code

<div class="document" id="hello">
<h1 class="title">Hello</h1>
<h2 class="subtitle" id="there">THERE</h2>
<pre class="code python literal-block"><span class="keyword namespace">import</span> <span class="name namespace">os</span>

<span class="name">env_hi</span> <span class="operator">=</span> <span class="name">os</span><span class="operator">.</span><span class="name">env</span><span class="punctuation">(</span><span class="literal string single">'hi'</span><span class="punctuation">)</span>
<span class="keyword">print</span><span class="punctuation">(</span><span class="name">env_hi</span><span class="punctuation">)</span>
</pre>
<!-- end code -->
</div>

[bartTC]

@thaxy you can generate CSS styles using the Pygments get_style_defs method; http://pygments.org/docs/quickstart/#example

but its easiest if you just take one of the pre-generated css files from here. https://github.com/richleland/pygments-css You may need to adjust the CSS a bit (change .highlight to .code)

[bartTC]

Nevermind, I didn't understand that properly on first read. Indeed, I have not seen the 'long' class names either so far, I have to investigate.

[thaxy]

Okay, I am looking at this for around 1h now and I couldn't find any solution yet. Thanks for your support. I will update you if I find something.

[bartTC]

@thaxy I was not able yet to generate a Pygments CSS file with "long" classnames, but Docutils has a setting syntax_highlight which controls it. It can be either long, short or none, where long is the default in Docutils — while short is used in Pygments itself, and with all the CSS files floating around.

http://docutils.sourceforge.net/docs/user/config.html#syntax-highlight

I could overwrite this setting in the RestructuredFilter code directly and make short the new default, but that would be backwards incompatible.

So you could either write your own rST markup filter, with these rst-formatter-settings, but the simplest way is to override filter settings for the existing rST markup filter. There's a feature to do this: https://django-markup.readthedocs.io/en/latest/filter_settings.html

These settings in your settings.py will do the trick:

MARKUP_SETTINGS = {
    'restructuredtext': {
        'settings_overrides': {
            'syntax_highlight': 'short'
        }
    }
}

---

Example:

In [1]: from django_markup.markup import formatter
In [2]: from django.conf import settings
In [3]: text = '''
   ...: Some **rST** text.
   ...:
   ...: .. code-block:: python
   ...:
   ...:     def test():
   ...:       return 'Hello World'
   ...: '''

Here the short setting:

In [4]: settings.MARKUP_SETTINGS = {
   ...:     'restructuredtext': {
   ...:         'settings_overrides': {
   ...:             'syntax_highlight': 'short'
   ...:         }
   ...:     }
   ...: }

In [5]: formatter(text, filter_name='restructuredtext')
Out[5]: u'<div class="document">\n<p>Some <strong>rST</strong> text.</p>\n<pre class="code python literal-block">\n<span class="k">def</span> <span class="nf">test</span><span class="p">():</span>\n  <span class="k">return</span> <span class="s1">\'Hello World\'</span>\n</pre>\n</div>\n'

And the long (default) setting:

In [6]: settings.MARKUP_SETTINGS = {
   ...:     'restructuredtext': {
   ...:         'settings_overrides': {
   ...:             'syntax_highlight': 'long'
   ...:         }
   ...:     }
   ...: }

In [7]: formatter(text, filter_name='restructuredtext')
Out[7]: u'<div class="document">\n<p>Some <strong>rST</strong> text.</p>\n<pre class="code python literal-block">\n<span class="keyword">def</span> <span class="name function">test</span><span class="punctuation">():</span>\n  <span class="keyword">return</span> <span class="literal string single">\'Hello World\'</span>\n</pre>\n</div>\n'