reStructuredText comments are breaking the html

[TierraDelFuego]

This file is meant to cause errors but I mention this because I am new to rst and wanted a full rst usage example doc as part of my site.
https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docs/user/rst/demo.txt

I fixed the errors until I got no more from Pelican but then I discovered that Pelican is not treating rst comments properly. At least not the comment(s) before the title in that demo.txt.

To reproduce you can probably take a snippet of demo.txt.

[TierraDelFuego]

The work around here BTW, is to just not place any text before the title. Maybe I expected pelican to adhere more strictly to reST spec. but may be that's unreasonable. Simplicity is good and with that in mind this can probably be closed. Unless someone thinks more strict adherence to the reST spec. is a goal worth pursuing.

[ingwinlu]

pelican does not do the reStructuredText parsing, we just use the docutils library

[leotrs]

Please close.

[TierraDelFuego]

Docutils doesn't have a problem with this case so Pelican is the problem.

So just to be clear on this issue @ingwinlu, @leotrs and @justinmayer agree that more strict adherence to reST spec is not a goal worth pursuing for Pelican.

[avaris]

@TierraDelFuego can you demonstrate what the problem is exactly?

It is also confusing when you say things like "docutils doesn't have a problem" whereas that document is expected to have errors (and it does).

Anyway, I downloaded the file, fixed errors, gave it a proper status and run pelican with it. Generated output is strikingly similar to the one docutils generates with its rst2html tool. And that isn't surprising at all, since they both do pretty much the same thing. Because pelican uses docutils to do all that.

PS: Just to illustrate...

Here is a few lines including the comments from the what pelican gets for the file's content

<div class="dedication topic">
<p class="topic-title first">Dedication</p>
<p>For Docutils users &amp; co-developers.</p>
</div>
<div class="abstract topic">
<p class="topic-title first">Abstract</p>
<p>This document is a demonstration of the reStructuredText markup
language, containing examples of all basic reStructuredText
constructs and many advanced constructs.</p>
</div>
<!-- This is a comment. Note how any initial comments are moved by
transforms to after the document title, subtitle, and docinfo. -->
<!-- Above is the document title, and below is the subtitle.
They are transformed from section titles after parsing. -->
<!-- bibliographic fields (which also require a transform): -->
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="auto-toc simple">

And here is what rst2html generates for the same section:

<div class="dedication topic">
<p class="topic-title first">Dedication</p>
<p>For Docutils users &amp; co-developers.</p>
</div>
<div class="abstract topic">
<p class="topic-title first">Abstract</p>
<p>This document is a demonstration of the reStructuredText markup
language, containing examples of all basic reStructuredText
constructs and many advanced constructs.</p>
</div>
<!-- This is a comment. Note how any initial comments are moved by
transforms to after the document title, subtitle, and docinfo. -->
<!-- Above is the document title, and below is the subtitle.
They are transformed from section titles after parsing. -->
<!-- bibliographic fields (which also require a transform): -->
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="auto-toc simple">