Allow for more pygments.formatters.html.HTMLFormatters options

[shimizukawa]

When using long code blocks, say the source code of a full source file which is referenced, it is useful to not only display the line numbers ( which is possible via the :linenos: role ) but also to reference individual lines marked as anchors. This is enabled by pygments in the HTMLFormatter using the lineanchors option. However this and other options of the same class are not supported by Sphinx.

It is possible to hack this into Sphinx easily adjusting the PygmentsBridge class:

if dest == 'html':
      self.fmter = {False: self.html_formatter(style=style)              
                        True: self.html_formatter(style=style, 
                                linenos=True,
                                lineanchors = 'L')}

It would be preferable to specify this in the code-block directive instead:

.. code-block:: c
    :linenos:
    :lineanchors:`L`

This together with appropriate semantic markup to reference the location. When missing one can fall back to the .. raw:: directive though, so providing a :lineanchors: attribute is of greater importance.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/747
• Originally reported by: schluehk
• Originally created at: 2011-08-05T05:02:16.789

[shimizukawa]

From Georg Brandl on 2011-09-22 10:03:52+00:00

Good idea. Should be much easier to implement now that we have a way to pass formatter options to the highlighter module.

[shimizukawa]

From Georg Brandl on 2014-10-18 07:32:18+00:00

Removing version: 1.0.7 (automated comment)

[sriv]

Hi - is there a way I can enable lineanchors without changing sphinx code? Happy to write my own override as an extension. thanks.

[tk0miya]

As a ad-hoc, you can use following code. It gives line anchors if you set label to the code-blocks.

from sphinx.writers.html import HTMLTranslator


class Highlighter(object):
    def __init__(self, highlighter):
        self.highlighter = highlighter
        self.node_id = None

    def set_node_id(self, node_id):
        self.node_id = node_id

    def highlight_block(self, *args, **kwargs):
        if self.node_id:
            kwargs.setdefault('lineanchors', self.node_id)

        return self.highlighter.highlight_block(*args, **kwargs)


class MyHTMLTranslator(HTMLTranslator):
    def __init__(self, builder, *args, **kwargs):
        HTMLTranslator.__init__(self, builder, *args, **kwargs)
        self.highlighter = Highlighter(builder.highlighter)

    def visit_literal_block(self, node):
        if node['ids']:
            self.highlighter.set_node_id(node['ids'][0])
        else:
            self.highlighter.set_node_id(None)

        HTMLTranslator.visit_literal_block(self, node)


def setup(app):
    app.set_translator('html', MyHTMLTranslator)

Note: pygments generates anchors like [label]-NNN. so it gets conflict if you have same labels.
We have to take care to the conflicts when we will update our HTML builder.

[sriv]

@tk0miya - Thank you very much for this snippet. It serves my need, with one small addition. I had to also add kwargs.setdefault('anchorlinenos', True) in the highlight_block method.

Previously, I attempted to set the html_formatter of the PygmentsBridge class to a custom one, which would set anchorlinenos to True, but I couldn't find an easy way to set lineanchors. Your suggestion is much better. Thanks again.