feat: support versioned docs by Xunzhuo · Pull Request #639 · envoyproxy/gateway

Xunzhuo · 2022-10-21T16:31:52Z

Resolves: #632

Take this as an example: https://gateway.merbridge.cn

For updates in DOC.md can read: https://gateway.merbridge.cn/v0.2.0/dev/DOCS.html
For updates in releasing.md can read: https://gateway.merbridge.cn/v0.2.0/dev/releasing.html

We can access the current release version of EG by https://gateway.merbridge.cn.

And we can access the latest version of EG by https://gateway.merbridge.cn/latest.

Or by clicking the latest docs at the footer of the pages, which redirects to the /latest pages of the site:

We can come back to the current release version of EG by clicking the index title, which redirects to the root page of the site:

Checkout the quickstart guides in two different versions:

Latest: https://gateway.merbridge.cn/latest/user/quickstart.html
Release v0.2.0: https://gateway.merbridge.cn/user/quickstart.html

Signed-off-by: bitliu bitliu@tencent.com

codecov-commenter · 2022-10-22T06:02:20Z

Codecov Report

Merging #639 (ba97a35) into main (592863a) will decrease coverage by 0.10%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #639      +/-   ##
==========================================
- Coverage   62.82%   62.72%   -0.11%     
==========================================
  Files          47       47              
  Lines        5762     5762              
==========================================
- Hits         3620     3614       -6     
- Misses       1912     1917       +5     
- Partials      230      231       +1

Impacted Files	Coverage Δ
internal/provider/kubernetes/gatewayclass.go	`73.91% <0.00%> (-1.45%)`	⬇️
internal/provider/kubernetes/gateway.go	`51.38% <0.00%> (-0.86%)`	⬇️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

phlax · 2022-10-22T09:58:41Z

slightly related to this - one problem we had with Envoy docs was that changelogs contained links to content that no longer existed - breaking sphinx in different ways or causing links to be updated to approximately related content

we resolved this by using intersphinx so that all the links in the changelogs are versioned and can point to the docs version where the change occurred.

its a bit of work to setup/maintain but it resolves the problem - not sure if you will have changelogs in docs - but if you will, its probably worth thinking about

Xunzhuo · 2022-10-22T15:23:11Z

Thanks for the comments and suggestions @phlax! I think at least for now, we did not meet such issues, and this PR is to init the versioned docs, which we do not support yet. I think maybe we can make it work at first, and optimize it later if we meet issues like you pointed.

danehans · 2022-10-24T04:57:37Z

@phlax #639 (comment) should not be an issue since we use GitHub-generated changelogs and have release-specific release notes. See the v0.2 release announcement as an example.

.github/workflows/docs.yaml

docs/v0.2.0/about_docs.rst

tools/make/docs.mk

arkodg · 2022-10-31T15:48:09Z

docs/index.html

is this generated or will someone need to update this as well as the VERSION file value during every release ?

The VERSION is generated too, so I think maybe we can generate this file too. Or we can just point to the latest not the current release

Can we just take this approach to update this value?

danehans · 2022-10-31T17:30:39Z

docs/v0.2.0/dev/DOCS.md

This should be docs/html to support versioned docs. Otherwise, code 404, message File not found when trying to access a versioned doc.

Thanks, I forgot to update this, Will be updated later.

Test locally and works fine.

danehans · 2022-10-31T18:02:46Z

This PR versions all the docs. Do all docs need to be versioned or just the user docs? THoughts @LukeShu @arkodg @Xunzhuo @skriss @AliceProxy @youngnick

Xunzhuo · 2022-10-31T18:24:37Z

This PR versions all the docs. Do all docs need to be versioned or just the user docs? THoughts @LukeShu @arkodg @Xunzhuo @skriss @AliceProxy @youngnick

IMO, we miss something like envoy-website and envoy-mobile site, they have the homepages separated with the docs, the homepage contains things which do not need to be versioned like blogs, announcements and etc. As for the the sphinx docs, they are all versioned.

So contents in sphinx docs would be better to be all versioned, we can just add our homepage support after this.

Take what istio has as an example:
non-versioned:

Blogs
Announcements
Get involved
About
Introduction
Case studies
FAQ
....

versioned: Documents.

This PR is already big enough, I can work on the non-versioned Homepages later, and finished in v0.3.0-rc1.

danehans

I run make docs-release TAG=v0.3.0 and see the v0.3.0 docs content is generated:

$ cat VERSION
v0.3.0

$ ls -al docs
total 8
...
drwxr-xr-x  17 daneyonhansen  staff   544 Nov  1 08:23 latest
drwxr-xr-x  17 daneyonhansen  staff   544 Nov  1 08:23 v0.2.0
drwxr-xr-x  17 daneyonhansen  staff   544 Nov  1 08:24 v0.3.0

However, the docs still default to v0.2.0 when I run locally.

danehans · 2022-11-01T15:33:07Z

docs/index.html

Can we just take this approach to update this value?

Xunzhuo · 2022-11-01T16:53:32Z

I run make docs-release TAG=v0.3.0 and see the v0.3.0 docs content is generated:
However, the docs still default to v0.2.0 when I run locally.

Thanks @danehans, right, we need to update the redirect index.html too. I will update this ASAP.

danehans · 2022-11-01T19:29:48Z

@Xunzhuo can you rebase and include #665 in this PR?

Signed-off-by: bitliu <bitliu@tencent.com>

Xunzhuo force-pushed the feat-versioned-docs branch 4 times, most recently from 93e0dff to 69e7caf Compare October 22, 2022 06:00

Xunzhuo force-pushed the feat-versioned-docs branch 8 times, most recently from 6cd7f7e to 9352bd1 Compare October 22, 2022 08:18

Xunzhuo mentioned this pull request Oct 22, 2022

feat: support user-facing version #609

Merged

Xunzhuo force-pushed the feat-versioned-docs branch 2 times, most recently from 8746d06 to 0614ccd Compare October 22, 2022 08:46

Xunzhuo mentioned this pull request Oct 22, 2022

Cleans-Up Docs #640

Merged

Xunzhuo marked this pull request as ready for review October 22, 2022 08:48

Xunzhuo requested a review from a team as a code owner October 22, 2022 08:48

arkodg reviewed Oct 24, 2022

View reviewed changes

.github/workflows/docs.yaml Show resolved Hide resolved

arkodg reviewed Oct 24, 2022

View reviewed changes

docs/v0.2.0/about_docs.rst Show resolved Hide resolved

arkodg reviewed Oct 24, 2022

View reviewed changes

tools/make/docs.mk Outdated Show resolved Hide resolved

Xunzhuo force-pushed the feat-versioned-docs branch 4 times, most recently from 08a93e9 to ba97a35 Compare October 29, 2022 08:44

Xunzhuo requested a review from arkodg October 29, 2022 10:15

Xunzhuo mentioned this pull request Oct 29, 2022

Missing release version in docs site #615

Closed

arkodg reviewed Oct 31, 2022

View reviewed changes

danehans suggested changes Oct 31, 2022

View reviewed changes

Xunzhuo requested a review from danehans November 1, 2022 06:04

Xunzhuo mentioned this pull request Nov 1, 2022

Support non-versioned Homepages #668

Closed

danehans reviewed Nov 1, 2022

View reviewed changes

docs/index.html Outdated

Copy link
Copy Markdown

Contributor

danehans Nov 1, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we just take this approach to update this value?

Xunzhuo added 3 commits November 2, 2022 10:55

feat: support versioned docs

3f16172

Signed-off-by: bitliu <bitliu@tencent.com>

update

e75824c

Signed-off-by: bitliu <bitliu@tencent.com>

resolve conflicts

32d9c4a

Signed-off-by: bitliu <bitliu@tencent.com>

Xunzhuo force-pushed the feat-versioned-docs branch from 285bdae to 32d9c4a Compare November 2, 2022 02:56

update

401c8e2

Signed-off-by: bitliu <bitliu@tencent.com>

Xunzhuo force-pushed the feat-versioned-docs branch from b066b5a to 401c8e2 Compare November 2, 2022 03:32

Xunzhuo requested review from arkodg and danehans November 2, 2022 03:32

danehans approved these changes Nov 2, 2022

View reviewed changes

arkodg merged commit 10eb279 into envoyproxy:main Nov 3, 2022

This was referenced Nov 3, 2022

Support Multiple Release Versions #689

Closed

EG will only support non transparent mode for L4 #673

Closed

Xunzhuo deleted the feat-versioned-docs branch November 11, 2022 07:13

Conversation

Xunzhuo commented Oct 21, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Oct 22, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

phlax commented Oct 22, 2022

Uh oh!

Xunzhuo commented Oct 22, 2022

Uh oh!

danehans commented Oct 24, 2022

Uh oh!

Uh oh!

Uh oh!

Uh oh!

arkodg Oct 31, 2022

Choose a reason for hiding this comment

Uh oh!

Xunzhuo Oct 31, 2022

Choose a reason for hiding this comment

Uh oh!

danehans Nov 1, 2022

Choose a reason for hiding this comment

Uh oh!

danehans Oct 31, 2022

Choose a reason for hiding this comment

Uh oh!

Xunzhuo Oct 31, 2022

Choose a reason for hiding this comment

Uh oh!

Xunzhuo Nov 1, 2022

Choose a reason for hiding this comment

Uh oh!

danehans commented Oct 31, 2022

Uh oh!

Xunzhuo commented Oct 31, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

danehans left a comment

Choose a reason for hiding this comment

Uh oh!

danehans Nov 1, 2022

Choose a reason for hiding this comment

Uh oh!

Xunzhuo commented Nov 1, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

danehans commented Nov 1, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Xunzhuo commented Oct 21, 2022 •

edited

Loading

codecov-commenter commented Oct 22, 2022 •

edited

Loading

Xunzhuo commented Oct 31, 2022 •

edited

Loading

Xunzhuo commented Nov 1, 2022 •

edited

Loading