Markup: github stopped showing my README.rst as reStructuredText

[jpluimers]

This fill still displays nicely in atom and generates correct html using pandoc, however github stopped showing it as reStructuredText between these two revisions:

• reStructuredText: https://github.com/jpluimers/OpenSuSE.Tumbleweed.Server-Install/blob/c79d45e66f715cde961910c0157ce5d595fe3881/README.rst
• plain text: https://github.com/jpluimers/OpenSuSE.Tumbleweed.Server-Install/blob/fa775521271df22962d9b3a40384c2d5aa39162f/README.rst

Am I doing something wrong? If so: what?
If not so: what should be fixed?

[gjtorikian]

That's really weird. Nothing stands out at me as alarming in the diff: https://github.com/jpluimers/OpenSuSE.Tumbleweed.Server-Install/compare/c79d45e66f715cde961910c0157ce5d595fe3881...master

I'll take a look into it for sure. Sorry for the trouble!

[jpluimers]

I must be overlooking something, as pandoc is also failing, but further down (so I didn't notice): the Table of Contents is missing even though the .. contents:: is still there and I think the ToC syntax is OK.

It even generates a warning for this:

pandoc: ignoring unknown directive: contents "source" (line 18, column 1)

If you have any idea about what could cause it, please let me know.

[jpluimers]

Some progress:

I've discovered rst2html.py which does a way better job at giving warnings and errors on reStructuredText syntax than pandoc.

As a result, I've updated the document at https://github.com/jpluimers/OpenSuSE.Tumbleweed.Server-Install/blob/master/README.rst

Pandoc handles it better now, but it still doesn't display correctly on github.

This might have to do with the below error for which I've sent an email as indicated in it:

jeroenp$ rst2html.py README.rst readme.html
README.rst:292: (ERROR/3) Too many autonumbered footnote references: only 0 corresponding footnotes available.
KeyError: 'refid'
Exiting due to error.  Use "--traceback" to diagnose.
Please report errors to <[email protected]>.
Include "--traceback" output, Docutils version (0.12 [release]),
Python version (2.7.5), your OS type & version, and the
command line used.

jeroenp$ rst2html.py README.rst readme.html --traceback
README.rst:292: (ERROR/3) Too many autonumbered footnote references: only 0 corresponding footnotes available.
Traceback (most recent call last):
  File "/usr/local/bin/rst2html.py", line 23, in <module>
    publish_cmdline(writer_name='html', description=description)
  File "/Library/Python/2.7/site-packages/docutils/core.py", line 352, in publish_cmdline
    config_section=config_section, enable_exit_status=enable_exit_status)
  File "/Library/Python/2.7/site-packages/docutils/core.py", line 219, in publish
    output = self.writer.write(self.document, self.destination)
  File "/Library/Python/2.7/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/Library/Python/2.7/site-packages/docutils/writers/html4css1/__init__.py", line 176, in translate
    self.document.walkabout(visitor)
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 166, in walkabout
    visitor.dispatch_visit(self)
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 1882, in dispatch_visit
    return method(node)
  File "/Library/Python/2.7/site-packages/docutils/writers/html4css1/__init__.py", line 986, in visit_footnote_reference
    href = '#' + node['refid']
  File "/Library/Python/2.7/site-packages/docutils/nodes.py", line 567, in __getitem__
    return self.attributes[key]
KeyError: 'refid'

[jpluimers]

Fixed the document. Now it renders fine again.

The failure to render seems to happen when the reStructuredText syntax isn't correct. It would be nice if the render failure would indicate what wasn't correct. The rst2html.py script (which you get by installing docutils ** does show what's wrong, though cryptic.

The final error (in human speak: you're referencing a footnote by a name that does not match any footnote):

README.rst:292: (ERROR/3) Too many autonumbered footnote references: only 0 corresponding footnotes available.

The error was fixed by this little change:

-The problem however is that this indeed minimal. It is enforced by the ``patterns-openSUSE-minimal_base-conflicts`` [#patterns-openSUSE-minimal_base-conflicts]_ pattern which is part of the minimal install.
+The problem however is that this indeed minimal. It is enforced by the ``patterns-openSUSE-minimal_base-conflicts`` [#patterns-openSUSE-minimal_base-conflicts_footnote]_ pattern which is part of the minimal install.

** Note that it is way easier to install docutils through pip and getting pip is really easy too.

[gjtorikian]

It would be nice if the render failure would indicate what wasn't correct.

We actually had a PR that did this--I'm having trouble finding it in this repo--but the design/CSS looked quite bad on the site. We haven't yet had a chance to revisit the idea. Duly noted that it could help fix some problems, though!

[rafaelcaricio]

@gjtorikian have you guys revisited that idea of making the errors in .rst visible in github interface? That would be so nice.

[raymondjplante]

I've got a .rst file that passes python setup.py checkdocs (collective.checkdocs) but rst files fail in github. Going to try the docutils library you suggest. Frustrating.

[ghost]

I wanted to point out that a completely empty README.rst is ignored as well, which confused me, I think other empty readme formats render don't they?