Syntax Highlighting with reStructuredText

kbits-theme uses Pygments’ “default” style for code syntax highlighting. Let’s see some examples!

reStructuredText has a built-in directive for syntax highlighting, the “code” directive. Here’s what the output of that directive looks like in kbits-theme:

from itertools import compress

def subsets(xs, nonempty=False, proper=False):
    """
    Returns an iterator over all subsets of the iterable ``xs`` as tuples.
    If ``nonempty`` is true, only nonempty subsets are returned.  If
    ``proper`` is true, only proper subsets are returned.
    """
    xs = tuple(xs)
    selectors = [False] * len(xs)
    while True:
        if not (
            (nonempty and not any(selectors)) or (proper and all(selectors))
        ):
            yield tuple(compress(xs, selectors))
        for i in xrange(len(selectors)):
            selectors[i] = not selectors[i]
            if selectors[i]:
                break
        else:
            break

… and here’s what it looks like with the :number-lines: option:

 1 from itertools import compress
 2 
 3 def subsets(xs, nonempty=False, proper=False):
 4     """
 5     Returns an iterator over all subsets of the iterable ``xs`` as tuples.
 6     If ``nonempty`` is true, only nonempty subsets are returned.  If
 7     ``proper`` is true, only proper subsets are returned.
 8     """
 9     xs = tuple(xs)
10     selectors = [False] * len(xs)
11     while True:
12         if not (
13             (nonempty and not any(selectors)) or (proper and all(selectors))
14         ):
15             yield tuple(compress(xs, selectors))
16         for i in xrange(len(selectors)):
17             selectors[i] = not selectors[i]
18             if selectors[i]:
19                 break
20         else:
21             break

Pelican provides a more featureful alternative to “code”, the “code-block” directive. The default output is pretty much the same as that of “code”, but if we enable table-style line numbers with the :linenos: option, we see a difference:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

from itertools import compress

def subsets(xs, nonempty=False, proper=False):
    """
    Returns an iterator over all subsets of the iterable ``xs`` as tuples.
    If ``nonempty`` is true, only nonempty subsets are returned.  If
    ``proper`` is true, only proper subsets are returned.
    """
    xs = tuple(xs)
    selectors = [False] * len(xs)
    while True:
        if not (
            (nonempty and not any(selectors)) or (proper and all(selectors))
        ):
            yield tuple(compress(xs, selectors))
        for i in xrange(len(selectors)):
            selectors[i] = not selectors[i]
            if selectors[i]:
                break
        else:
            break

The “code-block” directive also lets us highlight individual lines with the :hl_lines: option:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

from itertools import compress

def subsets(xs, nonempty=False, proper=False):
    """
    Returns an iterator over all subsets of the iterable ``xs`` as tuples.
    If ``nonempty`` is true, only nonempty subsets are returned.  If
    ``proper`` is true, only proper subsets are returned.
    """
    xs = tuple(xs)
    selectors = [False] * len(xs)
    while True:
        if not (
            (nonempty and not any(selectors)) or (proper and all(selectors))
        ):
            yield tuple(compress(xs, selectors))
        for i in xrange(len(selectors)):
            selectors[i] = not selectors[i]
            if selectors[i]:
                break
        else:
            break

… or make every n-th line number stand out:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

from itertools import compress

def subsets(xs, nonempty=False, proper=False):
    """
    Returns an iterator over all subsets of the iterable ``xs`` as tuples.
    If ``nonempty`` is true, only nonempty subsets are returned.  If
    ``proper`` is true, only proper subsets are returned.
    """
    xs = tuple(xs)
    selectors = [False] * len(xs)
    while True:
        if not (
            (nonempty and not any(selectors)) or (proper and all(selectors))
        ):
            yield tuple(compress(xs, selectors))
        for i in xrange(len(selectors)):
            selectors[i] = not selectors[i]
            if selectors[i]:
                break
        else:
            break

reStructuredText also provides a :code: role that can be used for highlighting inline code samples. To use it, first create a “subrole” with the name of the highlighted language supplied to the :language: option:

.. role:: py(code)
    :language: python

… and then you can write this:

Put :py:`"2" * 2` in the REPL to get :py:`"22"`.

… to get this:

Put "2" * 2 in the REPL to get "22".