[libvirt PATCH] meson: Ask rst2html to strip comments

[Michal Prívozník]

On 6/7/21 5:03 PM, Daniel P. Berrangé wrote:
> On Mon, Jun 07, 2021 at 04:52:41PM +0200, Pavel Hrdina wrote:
>> On Mon, Jun 07, 2021 at 04:39:15PM +0200, Michal Prívozník wrote:
>>> On 6/4/21 2:31 PM, Andrea Bolognani wrote:
>>>> They can be problematic: in particular, the rst files generated
>>>> by keycodemapdb's keymap-gen contain things like
>>>>
>>>>   To re-generate, run:
>>>>     keymap-gen --lang=rst --title=virkeycode-osx [...]
>>>>
>>>> which result in xsltproc later choking with
>>>>
>>>>   [1/12] Generating virkeyname-osx.html with a meson_exe.py custom command
>>>>   FAILED: docs/manpages/virkeyname-osx.html
>>>>   /usr/bin/meson --internal exe --capture docs/manpages/virkeyname-osx.html \
>>>>     /usr/bin/xsltproc [...] --nonet ../docs/subsite.xsl docs/manpages/virkeyname-osx.html.in
>>>>   docs/manpages/virkeyname-osx.html.in:17: parser error : Double hyphen within comment:
>>>>     keymap-gen --lang=rst --title=virkeyname-osx [...]
>>>
>>> I don't see this error. Do I need some very fresh version of something?
>>>
>>> $ rst2html.py --version
>>> rst2html.py (Docutils 0.16 [release], Python 3.9.4, on linux)
>>
>> You need the incorrect rst2html tool, see this explanation for example:
>>
>> https://gitlab.com/libvirt/libvirt/-/issues/139#note_528736524
>>
>> I'm not so sure about this patch. I think we should instead try to
>> detect what rst2html is used and error out if it is not the one provided
>> by docutils project.
> 
> I've looked detecting the wrong rst2html "binary" before, but I didn't
> see any attractive ways todo it.
> 

Well, aren't we looking at one example how to distinguish the two? I
mean, we can detect at configure time whether double hyphens within a
comment work and if not then we found broken rst2html tool.

> I wonder if the docutils python API is considered stable ?  If it is,
> then we could skip calling the system rst2html5 entirely, and just copy
> its contents into scripts/rst2html5. Then all we need to check is that
> docutils python API is installed, and we'll know we run the right thing.

Sounds good.

Michal