restore old documentation references #39086
Conversation
💊 CI failures summary and remediationsAs of commit d46d8c7 (more details on the Dr. CI page): 💚 💚 Looks good so far! There are no failures yet. 💚 💚 This comment was automatically generated by Dr. CI (expand for details).Follow this link to opt-out of these comments for your Pull Requests.Please report bugs/suggestions on the GitHub issue tracker or post in the (internal) Dr. CI Users group. This comment has been revised 6 times. |
|
That’s cool! 👍 I didn’t know we can override HTML writer in Sphinx before. |
docs/source/conf.py
Outdated
| ref = node.get('refuri') | ||
| ref_anchor = ref.split('#') | ||
| if len(ref_anchor) > 1: | ||
| self.body.append('<p id="{}"/p>'.format(ref_anchor[1])) |
There was a problem hiding this comment.
The p tag might introduce an empty line in some cases:
| Before | After |
|---|---|
 |
 |
 |
 |
We can consider changing it to a div tag: '<div id="{}" />'
There was a problem hiding this comment.
The tag should not be emitted here at all. Fixed with more hacks to filter out other references and use only the one that is relevant
There was a problem hiding this comment.
As a minor side note here, we don’t put p after / for self closing tags, so it should be something like <p id="..." />
|
I also noticed that multiple references might be added for the same method, and the browser will choose to get to the first occurrence. For example, https://5591729-65600975-gh.circle-artifacts.com/0/docs/torch.html#torch.max links to the middle of
|
The pandas theme does much more by using sphinx events but this PR is an attempt to keep it simple. If it needs more tweaking, maybe the event handling would be cleaner (or just use the javascript PR gh-39032). |
gchanan
added
the
triaged
|
@ShawnZhong is this still needed? |
|
Checked locally and works Example: brings users to the correct part of the documentation: |
facebook-github-bot
left a comment
facebook-github-bot
left a comment
There was a problem hiding this comment.
@jlin27 is landing this pull request. If you are a Facebook employee, you can view this diff on Phabricator.
Full details in master PR: #39086
7 participants
Fixes gh-39007
We replaced actual content with links to generated content in many places to break the documentation into manageable chunks. This caused references like
to become
The textual content that was located at the old reference was replaced with a link to the new reference. This PR adds a
<p id="xxx"/p>reference next to the link, so that the older references from outside tutorials and forums still work: they will bring the user to the link that they can then follow through to see the actual content.The way this is done is to monkeypatch the sphinx writer method that produces the link. It is ugly but practical, and in my mind not worse than adding javascript to do the same thing.