[Docutils-users] how to modify reST parsing?

[Tom Roche]

I use `restview`[1] mostly to locally preview reST documents before I push them to Bitbucket (BB). BB's reST parser accepts 4-char-length header/title underlines, e.g.,

summary
====

I prefer those, since they are easier to produce and search for. However my (Debian) laptop's `restview` does not: I get (e.g.)

System Message: WARNING/2 (./README.rst, line 13)xm
Title underline too short.
summary
====

I have put an issue on `restview`[2] regarding this. However, I strongly suspect the relevant parsing is being done by my laptop's `docutils` (which is a `restview` install dependency). Am I missing something?

If not: can I configure my system `docutils` so as *not* to emit this warning?

If feasible please reply to me as well as to the list, and TIA, Tom Roche <***@pobox.com>

[1]: https://pypi.python.org/pypi/restview
[2]: https://github.com/mgedmin/restview/issues/31

[Guenter Milde]

Post by Tom Roche
I use `restview`[1] mostly to locally preview reST documents before I
push them to Bitbucket (BB). BB's reST parser accepts 4-char-length
header/title underlines, e.g.,

summary
====

I prefer those, since they are easier to produce and search for.

However, they are not valid rST.
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections

Whether to call the Bitbucket rST parser broken or forgiving, is up to you.

Post by Tom Roche
However my (Debian) laptop's `restview` does not: I get (e.g.)

System Message: WARNING/2 (./README.rst, line 13)xm
Title underline too short.
summary
====

I have put an issue on `restview`[2] regarding this. However, I
strongly suspect the relevant parsing is being done by my laptop's
`docutils` (which is a `restview` install dependency). Am I missing
something?

This seems to be the case. The above System Message is another indicator:
it is a typical Docutils warning.

Post by Tom Roche
If not: can I configure my system `docutils` so as *not* to emit this warning?

This is easily possible via a configuration file.
See http://docutils.sourceforge.net/docs/user/config.html#report-level

However, this will not change parsing but only reporting: The above markup
example will still not be parsed as a section header.


Changing the parsing rules is far more difficult. It would imply writing a
custom parser (inheriting from the standard rST parser) and front-end
(calling the custom parser).

I'd rather recommend using an `editor that supports rST`__ and can insert a
section underline of correct lenght on the press of a key-combo.

__ http://docutils.sourceforge.net/docs/user/links.html#editors


Günter