Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

github doesn't display sphinx rst extensions #1371

Closed
pmaupin opened this Issue Jun 23, 2015 · 4 comments

Comments

Projects
None yet
3 participants
@pmaupin
Copy link

commented Jun 23, 2015

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:

https://github.com/rtfd/readthedocs.org/tree/master/docs/api.rst
http://docs.readthedocs.org/en/latest/api.html

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:

https://github.com/berkerpeksag/astor/tree/master/docs/index.rst

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:

https://github.com/github/markup/tree/master/lib/github/commands/rest2html

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.

Thanks,
Pat

@ericholscher

This comment has been minimized.

Copy link
Member

commented Jun 23, 2015

Agreed. There isn't really a great solution here. I think the best solution
is for GitHub not to silently remove all markup, but display it in some
kind of fashion so that people know they are missing the content.

There isn't really much we can do, and GitHub will never be able to render
the logic of all markup languages, so it's mostly just about letting people
know that they are missing content on the page.

On Tue, Jun 23, 2015 at 6:41 PM, Patrick Maupin notifications@github.com
wrote:

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:

https://github.com/rtfd/readthedocs.org/tree/master/docs/api.rst
http://docs.readthedocs.org/en/latest/api.html

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:

https://github.com/berkerpeksag/astor/tree/master/docs/index.rst

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:

https://github.com/github/markup/tree/master/lib/github/commands/rest2html

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.

Thanks,
Pat


Reply to this email directly or view it on GitHub
#1371.

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

@pmaupin

This comment has been minimized.

Copy link
Author

commented Jun 24, 2015

I have opened an issue against the github project referencing this issue:

github/markup#514

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...

Thanks,
Pat

@pmaupin

This comment has been minimized.

Copy link
Author

commented Jun 26, 2015

I have initiated a pull request against the github markup project for a proposed solution to this:

github/markup#516

Comments and counter-proposals from people who understand docutils more deeply than me are certainly welcome.

Thanks,
Pat

@gregmuellegger

This comment has been minimized.

Copy link
Contributor

commented Jun 29, 2015

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.