Tune Up The rst3 Command With Filters

[tbp1...@gmail.com]

The rst3 command turns a Leo tree into a ReStructured Text file or set of RsT files, ready to be processed, for example, by Sphinx.  But sometimes it doesn't quite get things right.

For example, RsT requires a blank line between sections of all kinds.  But rst3 doesn't add one, and sometimes seems to swallow one so that you need to remember to add two blank lines to the end of every node.  If you don't do this, your headings can look wrong, or the within-document navigation links may not work.

The code for the command has provisions for the user to add custom filters to adjust the conversion of both node headlines and bodies.  But there is no documentation I found that explains how to use them.  So here is the way I worked out.  You have to write a little script and use that as a command or a button.

Filters are functions that accept a "position" and return either the unmodified text, modified text, or even nothing.  You register the filter before use.  A body filter looks like this:

def ensure_blank_last_line(c, p): # Must have this signature

    """Make sure a node has at least one blank line at end."""

    lines = p.b.split('\n')

    last = lines[-1]

    if last.strip():

        lines.append('')

        # Return the text you want to use in place of the

        # original body text

        return('\n'.join(lines))

    return p.b

To use this filter, you have to create your own instance of the RstCommands class:

from leo.core.leoRst import RstCommands

rst = RstCommands(c)

Then you register your body filter:

rst.register_body_filter(ensure_blank_last_line)

A headline filter has the much the same signature:

def headline_filter(c, h):

    # process headline

    # return modified headline text

Register the headline filter:

rst.register_headline_filter(headline_filter)

Finally, run the whole thing:

rst.rst3()

You can attach this script to a button, or add it as a command in your @settings tree.  To use it, select a node in your rst tree and invoke your script.  It will run the same old rst command except it will use your filters.