[Docutils-users] Getting the reST source of a section node in a Sphinx extension

[Kayce B. <ka...@go...>]

Hello! I believe this is my first message in the Docutils community. I'm a
big fan of Sphinx and appreciate the core role that Docutils plays in
Sphinx. I subscribed to this list and am excited to be more active in the
community.

I'm working on a Sphinx extension. In my doctree-resolved handler I
recursively walk through all section nodes. When the extension detects
something that can be improved in the underlying content, it's often
possible for the extension to make the edits automatically. Is the line
property of the Node class the only reference back to the underlying
reStructuredText? Just wanted to check that there's no explicit reference
to the end line of the node, and I'm expected to manually compute the end
line. The manual computation has been kinda error-prone and brittle for me
so far. Seems like the implementation could be much simpler and bulletproof
if reST explicitly gave me the end line. Just wanted to make sure there's
no better way to do this.

One example of the manual computation I'm alluding to:


from docutils.nodes import section

def do_stuff(app, doc_tree, doc_name):
    for node in doc_tree.traverse(section):
        text = node.astext()
        start = node.line
        end = start + len(text.splitlines())  # Often incorrect
        …
        # A better approach might be to get the first and last lines
        # of text and search for those delimiters in the source

def setup(app):
    app.connect('doctree-resolved', do_stuff)
    return {
        'version': '0.0.0',
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }