Docs Publishing Strategy

[danehans]

Should Envoy Gateway's documentation be separate from Envoy's official docs or integrate with https://github.com/envoyproxy/envoy-website

[mattklein123]

cc @phlax. I think it would be fine to integrate this into the main site eventually but I would discuss with Ryan. It needs some thinking about flow and placement.

[phlax]

i think we can start building here, and then integrate once we are ready to do so

using sphinx/rst, we can link between docs sites so it should be fairly straightforward to start linking to stuff in the main site and then merge

i guess the first step is getting some ci up and running so that we have something to start dropping docs into

i guess the main question re merging is whether they will (always) be released together - if not it might be better to just host on the envoy website but with a different path - eg /docs/envoy-gateway/latest etc

[danehans]

@phlax thanks for all the great feedback. I prefer that the gateway project syncs releases with Envoy. I will discuss this with the community and update this issue accordingly.

xref: #15

[danehans]

i guess the main question re merging is whether they will (always) be released together - if not it might be better to just host on the envoy website but with a different path - eg /docs/envoy-gateway/latest etc

Initial feedback during this week's community meeting is that Gateway will not be released with Envoy.

cc: @youngnick @LukeShu

[arkodg]

trying to summarize this discussion regarding docs, please correct me if im wrong

• Envoy Gateway will use its own doc publishing pipeline to generate html content.
• This content will be pushed to https://github.com/envoyproxy/envoy-website under docs/envoy-gateway/<version>
• And will use a CI workflow in Envoy Gateway that raises PRs in https://github.com/envoyproxy/envoy-website every time new doc content is generated
• Envoy Gateway content will be available under a tab similar to https://www.envoyproxy.io/docs

[mattklein123]

cc @phlax on ^. I think we have moved away from pushing to envoy-website on every change. I would look at how we do it in Envoy now and model it on that.

[phlax]

so an explanation of how docs are/were built in Envoy

what we did

• PRs build/test html generation
• commits to main - pushed built docs to "latest" on website repo
• releases - pushed built docs to version on website repo

the problems

altho very litte changed in the docs from commit to commit - the commit hash did and this led to a diff with 1000s of changes on every main commit to the repo -> website-repo

over time the website repo became pretty much unusable - it was huge, and cloning/fetching was prone to failing

eventually i stripped out all the hash/main commits and removed the latest docs from the repo

what we do now

• PRs - build/test html in CI and publish to (gcloud) ci-local storage
• commits to main - publish rst to (gcloud) ci-local storage and trigger netlify, which in turns fetches the rst and builds the html from that
• release commits - publish built html

this has made the website alot easier to work with

the repo is still pretty large as there are a lot of historical versions, so we are currently looking at the possibility of moving some of these to a separate docs archive repo

[arkodg]

thanks for sharing the details @phlax !
so my takeaway is - Envoy Gateway will need a CI workflow similar to what Envoy has
when it wants to publish html content, and should ensure it publishes only during a tagged release / or merge to main( for latest) to reduce size of the website repo

Also based on #50 it looks like Envoy Gateway will generate its html using Kubebuilder docs .

[github-actions]

This issue has been automatically marked as stale because it has not had activity in the last 30 days. It will be closed in the next 7 days unless it is tagged "help wanted" or "no stalebot" or other activity occurs. Thank you for your contributions.

[github-actions]

This issue has been automatically closed because it has not had activity in the last 37 days. If this issue is still valid, please ping a maintainer and ask them to label it as "help wanted" or "no stalebot". Thank you for your contributions.

[kflynn]

I'll take this on, although it seems not possible to assign me right now. 😂

[danehans]

@mattklein123 @phlax @lizan I'm unable to assign @kflynn to the issue. Can someone advise?

[mattklein123]

I added explicit read access for the assignable team. I think that fixed it. Assigned.

[kflynn]

Thanks @mattklein123! #203 is a bare-bones first cut here.

[danehans]

xref

• updating contrib guide: Update Developer Guide #295
• quickstart guide: Quickstart Guide #275

[kflynn]

Summary of the current state of the world: we're using Sphinx to generate HTML from RST docs, and (for the moment) we're using GitHub Actions to publish said HTML to GitHub Pages (cf https://envoyproxy.github.io/gateway/).

@phlax Shall we just submit an Envoy PR to link out to the GitHub Pages version for now? Otherwise, we still need help getting everything published to GCS and hooked up with the Envoy docs...

[phlax]

i would say lets link it in initially - not sure exactly how/where - but i think that will be easiest

[arkodg]

@danehans @kflynn are we keeping this issue open to track eventually linking https://gateway.envoyproxy.io/v0.2.0/ to https://www.envoyproxy.io/docs ?

[danehans]

Let's keep our current strategy of using GH Pages to publish EG docs. If anyone disagrees, feel free to reopen.