On Friday, 8 March 2019 17:52:50 UTC+1, Rex East wrote: > > OK thanks, I will try that! > > On Thursday, March 7, 2019 at 2:03:50 AM UTC+9, Stefano David wrote: >> >> >> >> On Wednesday, 6 March 2019 15:55:58 UTC+1, Rex East wrote: >>> >>> Hi, I have a Sphinx project hosted on readthedocs.org. I want a way to >>> link from outside websites to a particular section in my documentation. And >>> I need it to be stable -- currently the URLs to sections look like this: >>> >>> >>> https://mysite.readthedocs.io/en/latest/models.html#built-in-fields-and-methods >>> >>> >>> But that URL is generated from the text of the section header, "Built-in >>> fields and methods". The link will break if I edit the section heading or >>> move that section to a different file in the documentation (not models.rst). >>> >>> Inside the project, I can use cross-references like: >>> >>> .. _FOO: >>> >>> and then >>> >>> :ref:`FOO` >>> >>> Which is great, but I cannot find a way to put these cross-references in >>> URLs. Any suggestions? >>> >> >> Assuming that the .. _FOO: label is in file models.rst, which in HTML >> becomes models.html, you can always reference is from the outside using >> https://mysite.readthedocs.io/en/latest/models.html#FOO, because any >> label will become an id="" in the HTML. If a particular section of the >> documentation is so important, add to it a label. >> >> In the case you move the content to another file, then my only idea is to >> keep the .. _FOO: label also in models.rst and eihter: 1) instead of the >> old content write something like "moved to new section" with a link or 2) >> add a javascript to models.html only, to (silently) redirect to the correct >> page. >> >> HTH, >> Stefano >> > Given that explicit section titles should/must be unique per Sphinx source directory (or else you'll see a warning), I wonder if we could do something more clever: use the intersphinx mapping file (objects.inv) <https://www.sphinx-doc.org/en/2.0/usage/extensions/intersphinx.html> to locate the cross reference and redirect the user to the new location. Either a web server extension could do that, or, we could produce a JSON variant of the intersphinx file and let some javascript redirect you to the right page if the anchor is not already on the current page. :-)
Both approaches have their pros and cons, I think. Perhaps somebody already started on something like this? HTH -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/sphinx-users. For more options, visit https://groups.google.com/d/optout.
