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
docs: Use intersphinx to map old versions and cleanup version history #16155
Conversation
566beb2
to
270d3b3
Compare
64c5f7a
to
eafab93
Compare
70d02d8
to
710c85e
Compare
need to investigate an issue with intersphinx... |
it seems that intersphinx has a very unhelpful "feature" (or > 6-year-old bug depending on pov sphinx-doc/sphinx#2068) by which it kinda guesses which set of docs a link belongs to. this means that by enabling intersphinx any broken links in current docs will happily pass if it can find the link in any of the linked documentation @nijel from weblate has submitted a patch to fix this (here - sphinx-doc/sphinx#8981) but afaict the sphinx devs either dont understand this bug (and how it makes intersphinx basically unusable - at least for versioning) or dont care too much (they are for these reasons i have included a patched version of intersphinx with @nijel 's fix |
dfd6ed3
to
bd5005c
Compare
Please comment on the pull request so that Sphinx developers can see there are more people wanting this ;-) |
fc756e0
to
4025cf6
Compare
3349bbb
to
cffb110
Compare
docs are rendered here https://storage.googleapis.com/envoy-pr/16155/docs/index.html |
cffb110
to
bc698a6
Compare
87dd781
to
d5ec851
Compare
@phlax what do you think the likelihood of getting this fixed upstream and landed soon is? I'm reluctant to take on this fork, but I also understand the concern. |
Yep - i think we definitely want to use this and it definitely has this bug/issue That means we have to choose the least bad option. The ones i considered
of those options the last seems the most straightforward - its ultimately a single module/file that had to be copied in i can add an Envoy ticket to remind us to remove it and use upstream once the issue is fixed. We may have to update it anyway if we upgrade to sphinx 4
sphinx 4 is currently in beta - not sure of the timescales to release. The PR for this was bumped 4 -> 4.1 - not sure why - it could just be that it needs rebasing (there were some very minor nits from my reading - which may/not be valid - tbh i dont understand why it wasnt just landed at the time) |
relatedly, ive begun testing the sphinx4 upgrade atm it blocks on sphinx-tabs - there is a PR with compat here executablebooks/sphinx-tabs#110 - so afaict once sphinx4 is out of beta that should unblock |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM modulo comment.
Signed-off-by: Ryan Northey <ryan@synca.io>
Signed-off-by: Ryan Northey <ryan@synca.io>
Signed-off-by: Ryan Northey <ryan@synca.io>
Signed-off-by: Ryan Northey <ryan@synca.io>
d08f7d3
to
ce24661
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, thanks!
@phlax needs format fix. |
seems to have format issues - i will fix tomorrow /wait |
Signed-off-by: Ryan Northey <ryan@synca.io>
…envoyproxy#16155) This PR - adds a patched version of intersphinx (~from sphinx-doc/sphinx#8981) - uses versioned refs for version history - cleans up inline literals in version history Signed-off-by: Ryan Northey <ryan@synca.io> Signed-off-by: Gokul Nair <gnair@twitter.com>
Signed-off-by: Ryan Northey ryan@synca.io
Commit Message: docs: Use intersphinx to map old versions and cleanup version history
Additional Description:
This PR
inline literals
in version historyRisk Level:
Testing:
Docs Changes:
Release Notes:
Platform Specific Features:
[Optional Runtime guard:]
[Optional Fixes #Issue]
[Optional Deprecated:]
[Optional API Considerations:]