Example for restructured text not workin

[oliver.metz@…]

Hi. This example from WikiRestructuredText is not working:

{{{
#!rst
 This is a reference to |a ticket|

 .. |a ticket| trac:: #42
}}}

This is a reference to |a ticket|

#12

System Message: WARNING/2 (<string>, line 3)

Substitution definition "a ticket" empty or invalid.

.. |a ticket| trac:: #12

Docutils System Messages

System Message: ERROR/3 (<string>, line 1); backlink

Undefined substitution referenced: "a ticket".

Also this one is not working with docutils-0.5 anymore. Perhaps this should be noted on TracInstall.

{{{
#!rst

See _`ticket:123`

 .. trac:: ticket:123 Ticket 123
}}}

2008-10-12 13:24:55,428 Trac[__init__] WARNING: HTML preview using <trac.mimeview.rst.ReStructuredTextRenderer object at 0xb5e806ec> failed 
(Directive "trac" must return a list of nodes.)
Traceback (most recent call last):
  File "/usr/lib/python2.5/site-packages/Trac-0.11stable_r7581-py2.5.egg/trac/mimeview/api.py", line 635, in render
    rendered_content, filename, url)
  File "/usr/lib/python2.5/site-packages/Trac-0.11stable_r7581-py2.5.egg/trac/mimeview/rst.py", line 208, in render
    'raw_enabled': 0})
  File "/usr/lib/python2.5/site-packages/docutils/core.py", line 433, in publish_parts
    enable_exit_status=enable_exit_status)
  File "/usr/lib/python2.5/site-packages/docutils/core.py", line 614, in publish_programmatically
    output = pub.publish(enable_exit_status=enable_exit_status)
  File "/usr/lib/python2.5/site-packages/docutils/core.py", line 204, in publish
    self.settings)
  File "/usr/lib/python2.5/site-packages/docutils/readers/__init__.py", line 69, in read
    self.parse()
  File "/usr/lib/python2.5/site-packages/docutils/readers/__init__.py", line 75, in parse
    self.parser.parse(self.input, document)
  File "/usr/lib/python2.5/site-packages/docutils/parsers/rst/__init__.py", line 157, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/lib/python2.5/site-packages/docutils/parsers/rst/states.py", line 170, in run
    input_source=document['source'])
  File "/usr/lib/python2.5/site-packages/docutils/statemachine.py", line 232, in run
    context, state, transitions)
  File "/usr/lib/python2.5/site-packages/docutils/statemachine.py", line 420, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.5/site-packages/docutils/parsers/rst/states.py", line 2239, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python2.5/site-packages/docutils/parsers/rst/states.py", line 2251, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python2.5/site-packages/docutils/parsers/rst/states.py", line 1994, in directive
    directive_class, match, type_name, option_presets)
  File "/usr/lib/python2.5/site-packages/docutils/parsers/rst/states.py", line 2051, in run_directive
    'Directive "%s" must return a list of nodes.' % type_name

[rblank]

After a lot of digging, I found that this is a regression due to the fix for #1302. The fix involved wrapping a reference in a paragraph, because references don't work as children of a document. But it seems that you can't have a substitution return a paragraph. If I remove the wrapping into a paragraph, substitutions work again, but not references.

I'm a bit puzzled about the correct way to handle that. Should I try to detect when the returned item will be a child of the document? This smells fishy. I'll try to see if I can use another wrapper that works in all situations.

[rblank]

Ok, I got it. Here's what the docutils documentation says about directives:

For ordinary directives, the list must contain body elements or structural elements. Some directives are intended specifically for substitution definitions, and must return a list of Text nodes and/or inline elements (suitable for inline insertion, in place of the substitution reference). Such directives must verify substitution definition context, typically using code like this:

if not isinstance(state, states.SubstitutionDef):
    error = state_machine.reporter.error(
        'Invalid context: the "%s" directive can only be used '
        'within a substitution definition.' % (name),
        nodes.literal_block(block_text, block_text), line=lineno)
    return [error]

So I added a context check in [7759]. It also fixes the exception mentioned in the ticket description, by returning a list of nodes instead of a node.