Github and .rst files

[ardalis]

In the style guide, it says:

• Some programs parse .rst with rst2html_, which cannot interpret some
  Sphinx's directives such as code-block. So readers using such programs
  actually lose some content.

  As an example, well known Github_ platform uses rst2html
  to render .rst files in its repository browser. Not only you lose
  content, you also lose features like links to lines.

This doesn't appear to be the case (any longer). I uploaded a test here:
https://github.com/ardalis/Docs/blob/master/docs/github-test.rst

And it renders just fine (images are broken, but that's because I didn't copy them - code blocks render just fine, and no content is lost). When editing the file, it opens in a plain text editor, showing all RST markup, so again there doesn't appear to be any risk of loss of content when using .rst extension files and Github.

Can you comment and/or update the style guide?

Thanks!
Steve

[benoitbryon]

Hi @ardalis :)

Thanks for the report. Feel free to pull-request some changes, I'll be glad to review them ;)

So Github now renders code-block correctly, cool! The code-block example should be changed as you suggest.

Can Github render Sphinx-specific directives such as .. autoclass:: or .. literal-include::? See http://sphinx-doc.org/markup/index.html#sphinxmarkup for examples. Last time I tried it, the specific directives were hidden, so the content shown by Github was missing important items.

Also, is there a way to have an URL to highlight a specific line in a .rst file? Such as https://github.com/benoitbryon/documentation-style-guide-sphinx/blob/master/docs/style-guide.txt#L40? It seems https://github.com/ardalis/Docs/blob/master/docs/github-test.rst#L40 does not highlight line 40.

My personal taste is: Github's primary purpose is to share (raw) code, not to transform it for rendering. Whereas Github's pages or ReadTheDocs are made to publish HTML rendered out of reStructuredText. That's why I'm not a big fan of automatic rst2html rendering at Github. But I agree that's my very personal taste, and I understand arguments in favor of .rst too.

For having discussed quite a lot about .txt VS .rst, I learned that many developers actually prefer .rst extension, whatever the argues above or docutil's recommendation. If it is a never ending debate, perhaps the style guide should just highlight pros and cons and let the users decide, depending on the features they want. Because we actually do not want to spend hours in a debate about file extensions, do we? We had better just choose the one we like, for the reasons that are most valuable to us.

So, I would say it is a matter of personal taste, and yes the style guide may be updated that way.

Quite a long time since I updated the style guide... I think rst2rst (aka rstlint) has higher priority... but quite a long time since I worked on rst2rst also :(
So, again, feel free to pull-request some changes, and I'll be glad to review them ;)

[benoitbryon]

Tagged as "bug" because there is something wrong in the documentation.

[sypets]

Some more thoughts on using .rst or .txt:

• If you use sphinx-quickstart, it uses .rst as default. It prints out the following on setup:

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]: 

• What about IDEs and editors? Using .rst gives a hint about the file type and can be used by IDEs for syntax highlighting and syntax checking.