Open ardalis opened 9 years ago
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 ;)
Tagged as "bug" because there is something wrong in the documentation.
Some more thoughts on using .rst or .txt:
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]:
In the style guide, it says:
Some programs parse
.rst
withrst2html
_, which cannot interpret some Sphinx's directives such ascode-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