Join GitHub today
github doesn't display sphinx rst extensions #1371
This is something that maybe should be fixed at the github project, but all the people who understand docutils deeply are probably here :)
For example, these are nominally the same pages:
But someone reading the first page doesn't know what they are missing -- that there is actually content under the different "API endpoints." The problem is even worse for other projects, that are attracting users who may not know that much about readthedocs.
For example, I spent some time documenting functions and classes here:
But you wouldn't know that by reading it, unless you clicked the "raw" button or went to readthedocs. And, to a casual user browsing at github, documenting functions is just something I didn't bother to do. They won't know to go to readthedocs or to click the button -- they'll just think that I didn't document that stuff.
Now, maybe there's a badge to fix this or something (or maybe there should be). But if so, I didn't find it (and found that at least some of your content suffers from the same issue). Or maybe there is a good way to fix it in github's rst2html generator -- not necessarily to make nice-looking files, just to not treat all unknown directives as comments to throw away. That code is on github, too, and they obviously accept pull requests:
Or maybe the right answer is to use .txt as the file extension (or use a special directive) so that github doesn't try to format it at all. Of course, then a lot of text editors will have to be reconfigured. I don't know the right answer. All I know is that you have created an awesome thing here, but the default way that people are told to use it and actually do use it doesn't play nicely with trying to generate stuff that is accurately displayed to people browsing a source code repo at github.
Agreed. There isn't really a great solution here. I think the best solution
There isn't really much we can do, and GitHub will never be able to render
On Tue, Jun 23, 2015 at 6:41 PM, Patrick Maupin firstname.lastname@example.org
referenced this issue
Jun 24, 2015
I have opened an issue against the github project referencing this issue:
If it's OK with you, I'd like to leave this open here until it's fixed -- while the best fix probably implicates a change to that codebase rather than this one, and while you are right that it is not theoretically a readthedocs issue, (a) in a very practical sense it is a readthedocs issue, in the sense that most of the repositories affected are probably using readthedocs and "here be dragons" for people using both readthedocs and github, and (b) I'm still hopeful that someone here might stumble across the issue and know the easy one-line fix (ok, plus maybe a few lines of stylesheet) to make docutils not discard anything...
@pmaupin Awesome work! Thanks for all the effort, this is definitely a win when this gets merged.
I'm closing this issue as it is not readthedocs related. Feel free to re-open or create another ticket if there is something that we can do on readthedocs end to help this issue.