make css highlight style configurable

[jakevdp]

For blogging with ipython notebook, it's important to be able to control the CSS tag used for pygments highlighting (the style name "highlight" can conflict with the default settings on some blogging platforms). Currently this is configurable for the cell rendering using a custom filter, but for the css the value hard-coded in CSSHtmlHeaderTransformer. This PR makes the value configurable there as well.

This may not be the best way to go about this, but here's an example script for how the highlight tag can be configured using the changes in this PR. Note this also needs #3512 in order to properly register the custom filter.

There may well be a better way to accomplish this using the config object, or perhaps even adding a configurable value to the HtmlExporter class. I'm not entirely familiar with the IPython configurables & traitlet system, and would appreciate some feedback.

from IPython.nbconvert.filters.highlight import _pygment_highlight
from pygments.formatters import HtmlFormatter

from IPython.nbconvert.exporters import FullHtmlExporter
from IPython.config import Config

from IPython.nbformat import current as nbformat


def my_highlight(source, language='ipython'):
    formatter = HtmlFormatter(cssclass='highlight-ipynb')
    return _pygment_highlight(source, formatter, language)


class MyHtmlExporter(FullHtmlExporter):
    def __init__(self, *args, **kwargs):
        super(MyHtmlExporter, self).__init__(*args, **kwargs)
        self.register_filter('highlight', my_highlight)

    @property
    def default_config(self):
        c = Config({'CSSHtmlHeaderTransformer':
                    {'enabled':True, 'highlight_class':'highlight-ipynb'}})
        c.merge(super(MyHtmlExporter,self).default_config)
        return c


if __name__ == '__main__':
    infile = 'test_notebook.ipynb'
    outfile = 'test_notebook.html'

    print "converting {0} to {1}".format(infile, outfile)
    notebook = open(infile).read()
    notebook_json = nbformat.reads_json(notebook)

    exportHtml = MyHtmlExporter()
    (body,resources) = exportHtml.from_notebook_node(notebook_json)

    open(outfile, 'w').write(body)

[minrk]

If you want to make it configurable, it should be a trait with config=True on the class.

[jakevdp]

If you want to make it configurable, it should be a trait with config=True on the class.

I'm not entirely sure what that means... could you provide an example?

[Carreau]

from IPython.utils.traitlets import Unicode

class CSSHtmlHeaderTransformer(ActivatableTransformer):
    highlight_class = Unicode('default value', config=True, help='blahbah')
    # help text could be printed by --help-all

    def method(self):
        print(self.highlight_class) # will be the value of c.CSSHtmlHeaderTransformer.highlight_class if set.

(will develop on the trait class later when more time)

[jakevdp]

Thanks! I made the appropriate changes, and will also edit the code snippet in the description.

[Carreau]

HTML has been uppercased a few hours ago, and you are also not obliged to subclass, cf the following :

from IPython.nbconvert.filters.highlight import _pygment_highlight
from pygments.formatters import HtmlFormatter

from IPython.nbconvert.exporters import FullHTMLExporter
from IPython.config import Config

from IPython.nbformat import current as nbformat


def my_highlight(source, language='ipython'):
    formatter = HtmlFormatter(cssclass='highlight-ipynb')
    return _pygment_highlight(source, formatter, language)

c = Config({'CSSHtmlHeaderTransformer':
                    {'enabled':True, 'highlight_class':'highlight-ipynb'}})

exportHtml = FullHTMLExporter( config=c , filters={'highlight': my_highlight} )
(body,resources) = exportHtml.from_notebook_node(jake_notebook)

[jakevdp]

@Carreau - thanks, that makes sense!

Aside from HTML capitalization, do you think this modification of CSSHtmlHeaderTransformer is a useful addition?

[Carreau]

@Carreau - thanks, that makes sense!

No problem you are probably one of the person outside of IPython core team that sell the notebook the best, that the least we can do.

Aside from HTML capitalization, do you think this modification of CSSHtmlHeaderTransformer is a useful addition?

Yes, I think it make sens as nbconvert will probably be used in many pelican blog :-)

[Carreau]

I would put the '.' in the default value, this could allow people to add more 'complex' style defs like div.foo ipynb-render without prepending a dot. Thought ?

[jakevdp]

Good call

[Carreau]

Thanks, merged.