doc generation fails with python-docutils 0.8 - :hg: gives invalid option block

[Mads Kiilerich]

On 04/30/2012 04:13 PM, Martin Geisler wrote:
> Mads Kiilerich<mads at kiilerich.com>  writes:
>> I researched it a bit and found that the new behaviour kind of makes
>> sense but is annoying.
>
> Just to spell it out: what you're saying is that the correct syntax has
> always been
>
>    .. note::
>
>       Foo bar.

Yes ... no, that was not what I was trying to say ... but it is very 
close to what I should have said ;-)

Rephrasing and clarifying it a bit:

This fails with docutils 0.8:

.. note::
   :hg:`hello` world

These works with docutils 0.8 when generating man and html:

.. note::

   :hg:`hello` world

.. note::
   hello :hg:`world`

So it seems like '.. note::' just has to be followed by an empty line.

> Unfortunately this doesn't work in minirst. We'll need to rework minirst
> to do proper nesting at some point -- that should make this easier.

Oh - right. minirst as used by 'hg help' will render the 3 examples above as

     Note:
       "hg hello" world

       :hg:`hello` world

     Note:
       hg "hello" world

where the second :hg: will be considered a literal block because minirst 
assume that an admonition only has one (possibly empty) block and the 
following block is indented.

The right solution is to require an empty line after '.. note::' ... 
when no-longer-so-minirst can handle it.

/Mads