docs: Use intersphinx to map old versions and cleanup version history by phlax · Pull Request #16155 · envoyproxy/envoy

phlax · 2021-04-24T08:17:23Z

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

adds a patched version of intersphinx (~from intersphinx: Allow strict prefix matching sphinx-doc/sphinx#8981)
uses versioned refs for version history
cleans up inline literals in version history

Risk Level:
Testing:
Docs Changes:
Release Notes:
Platform Specific Features:
[Optional Runtime guard:]
[Optional Fixes #Issue]
[Optional Deprecated:]
[Optional API Considerations:]

docs/root/version_history/v1.10.0.rst

docs/root/version_history/v1.11.0.rst

docs/root/version_history/v1.13.0.rst

phlax · 2021-04-25T12:36:32Z

need to investigate an issue with intersphinx...

phlax · 2021-04-25T13:46:00Z

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 +-0 to fixing ?) and it wont be fixed until at least sphinx==4.1

for these reasons i have included a patched version of intersphinx with @nijel 's fix

nijel · 2021-04-25T14:29:09Z

Please comment on the pull request so that Sphinx developers can see there are more people wanting this ;-)

phlax · 2021-04-25T19:10:37Z

docs are rendered here https://storage.googleapis.com/envoy-pr/16155/docs/index.html

htuch · 2021-04-25T23:49:19Z

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

phlax · 2021-04-26T06:49:11Z

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

live with the bug and hope we dont accidentally add/remove link targets
build the docs twice - first removing the extension and all version info, and then readding it
create a separate intersphinx package somewhere
dynamically patch the module during docs build - ie curl ... > _ext/intersphinx.py && patch ...
copy the module into the repo and just add the fix

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

what do you think the likelihood of getting this fixed upstream and landed soon is?

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)

phlax · 2021-04-26T08:22:39Z

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

docs/_ext/intersphinx_custom.py

htuch

LGTM modulo comment.

Signed-off-by: Ryan Northey <ryan@synca.io>

htuch

LGTM, thanks!

htuch · 2021-04-27T00:06:33Z

@phlax needs format fix.

phlax · 2021-04-27T00:07:41Z

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>

phlax marked this pull request as draft April 24, 2021 08:17

phlax force-pushed the docs-version-histories branch from 566beb2 to 270d3b3 Compare April 24, 2021 10:45

phlax commented Apr 24, 2021

View reviewed changes

docs/root/version_history/v1.10.0.rst Outdated Show resolved Hide resolved

phlax commented Apr 24, 2021

View reviewed changes

docs/root/version_history/v1.10.0.rst Outdated Show resolved Hide resolved

phlax commented Apr 24, 2021

View reviewed changes

docs/root/version_history/v1.11.0.rst Outdated Show resolved Hide resolved

phlax force-pushed the docs-version-histories branch from 64c5f7a to eafab93 Compare April 25, 2021 08:24

phlax commented Apr 25, 2021

View reviewed changes

docs/root/version_history/v1.13.0.rst Outdated Show resolved Hide resolved

phlax force-pushed the docs-version-histories branch from 70d02d8 to 710c85e Compare April 25, 2021 09:19

phlax changed the title ~~[WIP] docs: Use intershpinx to map old versions~~ docs: Use intershpinx to map old versions Apr 25, 2021

phlax changed the title ~~docs: Use intershpinx to map old versions~~ docs: Use intersphinx to map old versions Apr 25, 2021

phlax marked this pull request as ready for review April 25, 2021 09:23

phlax requested a review from htuch April 25, 2021 09:23

phlax changed the title ~~docs: Use intersphinx to map old versions~~ [WIP] docs: Use intersphinx to map old versions Apr 25, 2021

phlax marked this pull request as draft April 25, 2021 12:36

phlax force-pushed the docs-version-histories branch from dfd6ed3 to bd5005c Compare April 25, 2021 13:55

phlax force-pushed the docs-version-histories branch 5 times, most recently from fc756e0 to 4025cf6 Compare April 25, 2021 15:14

phlax changed the title ~~[WIP] docs: Use intersphinx to map old versions~~ [WIP] docs: Use intersphinx to map old versions and cleanup version history Apr 25, 2021

phlax force-pushed the docs-version-histories branch 2 times, most recently from 3349bbb to cffb110 Compare April 25, 2021 19:08

phlax changed the title ~~[WIP] docs: Use intersphinx to map old versions and cleanup version history~~ docs: Use intersphinx to map old versions and cleanup version history Apr 25, 2021

phlax marked this pull request as ready for review April 25, 2021 19:09

phlax force-pushed the docs-version-histories branch from cffb110 to bc698a6 Compare April 25, 2021 19:13

phlax force-pushed the docs-version-histories branch 5 times, most recently from 87dd781 to d5ec851 Compare April 25, 2021 19:59

htuch reviewed Apr 26, 2021

View reviewed changes

docs/_ext/intersphinx_custom.py Outdated Show resolved Hide resolved

htuch reviewed Apr 26, 2021

View reviewed changes

phlax added 4 commits April 26, 2021 20:14

docs: Use intersphinx to map old versions

6f8f3b0

Signed-off-by: Ryan Northey <ryan@synca.io>

intersphinx_custom

d60b722

Signed-off-by: Ryan Northey <ryan@synca.io>

inline-literals

6306f63

Signed-off-by: Ryan Northey <ryan@synca.io>

add workaround comment

ce24661

Signed-off-by: Ryan Northey <ryan@synca.io>

phlax force-pushed the docs-version-histories branch from d08f7d3 to ce24661 Compare April 26, 2021 19:15

htuch previously approved these changes Apr 27, 2021

View reviewed changes

repokitteh-read-only bot added the waiting label Apr 27, 2021

phlax added 2 commits April 27, 2021 08:22

Merge branch 'main' into docs-version-histories

da6ac26

Signed-off-by: Ryan Northey <ryan@synca.io>

format

1cceb05

Signed-off-by: Ryan Northey <ryan@synca.io>

phlax dismissed htuch’s stale review via 1cceb05 April 27, 2021 07:25

repokitteh-read-only bot removed the waiting label Apr 27, 2021

phlax added 2 commits April 27, 2021 09:11

merge

cc78aff

Signed-off-by: Ryan Northey <ryan@synca.io>

fix-v1.8

6436dd9

Signed-off-by: Ryan Northey <ryan@synca.io>

phlax mentioned this pull request Apr 27, 2021

docs: Remove api v2 #16077

Merged

htuch approved these changes Apr 27, 2021

View reviewed changes

htuch merged commit 4a0dfd5 into envoyproxy:main Apr 27, 2021

Conversation

phlax commented Apr 24, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

phlax commented Apr 25, 2021

Uh oh!

phlax commented Apr 25, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nijel commented Apr 25, 2021

Uh oh!

phlax commented Apr 25, 2021

Uh oh!

htuch commented Apr 25, 2021

Uh oh!

phlax commented Apr 26, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

phlax commented Apr 26, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

htuch left a comment

Choose a reason for hiding this comment

Uh oh!

htuch left a comment

Choose a reason for hiding this comment

Uh oh!

htuch commented Apr 27, 2021

Uh oh!

phlax commented Apr 27, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

phlax commented Apr 24, 2021 •

edited

Loading

phlax commented Apr 25, 2021 •

edited

Loading

phlax commented Apr 26, 2021 •

edited

Loading

phlax commented Apr 26, 2021 •

edited

Loading