links in INSTALL don't work on both github and readthedocs #2835

New Issue

warner · 2016-09-28T08:15:51Z

warner commented

2016-09-28 08:15:51 +00:00

Currently, docs/INSTALL.rst uses ``about.rst_ and .. _about.rst: about.rst to generate a hyperlink to docs/about.rst (and the same for windows.rst and OS-X.rst). This works for github's RST renderer, but yields broken links on Read The Docs.

[02362ae] changed this from :doc:about``, which worked on Read The Docs but not on github.

We need a syntax that works on both renderers.

I'd like to get this fixed for 1.12, but I'm willing to drop it if nobody has a bright idea about how to make it work in both places.

Currently, `docs/INSTALL.rst` uses ``about.rst`_` and `.. _about.rst: about.rst` to generate a hyperlink to `docs/about.rst` (and the same for `windows.rst` and `OS-X.rst`). This works for github's RST renderer, but yields broken links on [Read The Docs](http://tahoe-lafs.readthedocs.io/en/latest/INSTALL.html). [02362ae] changed this from `:doc:`about``, which worked on Read The Docs but not on github. We need a syntax that works on both renderers. I'd like to get this fixed for 1.12, but I'm willing to drop it if nobody has a bright idea about how to make it work in both places.

warner added the

labels 2016-09-28 08:15:51 +00:00

warner added this to the 1.12.0 milestone 2016-09-28 08:15:51 +00:00

warner commented

2016-12-12 15:41:41 +00:00

For reference, I think https://github.com/github/markup might define how github does rendering.

I haven't yet found a syntax that works in both places, because ReadTheDocs (which is really just Sphinx-as-a-service) generates/serves .html files, whereas GitHub knows the files by their original .rst names. Sphinx knows which files it has translated, so a :doc: link will point to the post-translation name (.html), but GitHub has no such translation.

My inclination at this point is to use ReadTheDocs syntax, and add a docs/README that says "if you're reading this on github, please follow this link to readthedocs instead, where the hyperlinks will be rendered properly". And maybe add a single extra link or two from just the INSTALL doc (i.e. provide both syntaxes) if we think it's likely that many people will end up reading it there.

For reference, I think <https://github.com/github/markup> might define how github does rendering. I haven't yet found a syntax that works in both places, because ReadTheDocs (which is really just Sphinx-as-a-service) generates/serves .html files, whereas GitHub knows the files by their original .rst names. Sphinx knows which files it has translated, so a `:doc:` link will point to the post-translation name (.html), but GitHub has no such translation. My inclination at this point is to use ReadTheDocs syntax, and add a docs/README that says "if you're reading this on github, please follow this link to readthedocs instead, where the hyperlinks will be rendered properly". And maybe add a single extra link or two from just the INSTALL doc (i.e. provide both syntaxes) if we think it's likely that many people will end up reading it there.

warner commented

2016-12-12 15:57:07 +00:00

Github's .rst renderer is using the same docutils that Sphinx uses, but the :doc: handler lives in Sphinx, not docutils (https://github.com/sphinx-doc/sphinx/blob/1.5/sphinx/roles.py#L327). So Github won't be able to handle any of those special links.

Github's .rst renderer is using the same `docutils` that Sphinx uses, but the `:doc:` handler lives in Sphinx, not docutils (<https://github.com/sphinx-doc/sphinx/blob/1.5/sphinx/roles.py#L327>). So Github won't be able to handle any of those special links.

Brian Warner <warner@lothar.com> commented

2016-12-12 21:57:54 +00:00

In 91047bf/trunk:

docs: clean up .rst and references

This uses Read-The-Docs (sphinx/docutils) references exclusively, but adds a
README.md for GitHub viewers to remind them that the links there won't
work (closes ticket:2835).

It also fixes all the dangling references and other Sphinx warnings.

The "Preparation" section of docs/magic-folder-howto.rst was removed, since
this feature has since been merged to trunk.

In [91047bf/trunk](/tahoe-lafs/trac-2024-07-25/commit/91047bf828e0fd3cf1cfa674963234851de4211d): ``` docs: clean up .rst and references This uses Read-The-Docs (sphinx/docutils) references exclusively, but adds a README.md for GitHub viewers to remind them that the links there won't work (closes ticket:2835). It also fixes all the dangling references and other Sphinx warnings. The "Preparation" section of docs/magic-folder-howto.rst was removed, since this feature has since been merged to trunk. ```

tahoe-lafs added the

fixed

label 2016-12-12 21:57:54 +00:00

tahoe-lafs closed this issue

2016-12-12 21:57:54 +00:00

Sign in to join this conversation.