Streamline CI for faster docs iterations

[gunnar-solo]

What already exists

At present, gloo has a rather complicated/nested build processes in place to publish docs:

1. create docs changes: a. open a PR, solicit reviews b. solicit reviews, get approved c. pass CI, merge to master
2. manager active_versions.json to specify which versions of gloo should generate docs
3. build and publish site (for all supported gloo versions) a. docs-gen.yaml b. make build-site c. build-docs.sh d. make site-release

What's the problem?

This process leaves a lot to be desired. Notably, it...

1. is slow to add changes-->publishing new site
2. has no manual trigger
3. is awkward to maintain LTS branch docs (based on active_versions.json)

How do we make it better?

So! There is room for several quick wins/improvements. This issue is explicitly to do them. From a meeting with @gunnar-solo, @sam-heilbron, and @Nadine2016, it was discussed to...

1. Make active_vesrions.json not depend on Major.Minor.Patch but instead Major.Minor.x. Confirm that releases work
2. Make docs PRs skip tests on command
3. Expose manual trigger for job to kick off docs (optional, we might not need)

Why not revamp the entire system?

This was briefly touched on, then rejected. Ultimately, docs are being lifted to a single, centralized place across the solo org. A.K.A.: anything done, here, is meant to be a stopgap solution to make life "nicer" in the pre-lift times (author's guess: the next 8 months)

[sam-heilbron]

One aspect that we haven't discussed with this work: https://github.com/solo-io/gloo/blob/master/docs/content/static/content/version_gee_n%2B1.md is a manually maintained file. Can we automate this somehow so the docs team doesn't have to push changes with these values? How beneficial would this be @Nadine2016?

[gunnar-solo]

adding some closing context to this issue:

There are a couple of asks to the issue that were not addressed at the time of closing. Namely:

1. add the ability to skip CI -- the idea was that we could add a comment directive/github tag/changelog directive to stop CI from taking place, thus enabling faster merges on PRs which didn't warrant such scrutiny. Ex: spelling change/broken link. Gloo Mesh already has a useful, working solution that can be copied, if desired
2. auto-update versioning variables -- we have some versioning files which are currently manually updated. They are referenced throughout the docs as a way of saying "N+1" or similar such things. The ask is to auto-update these files, either on release or on docs publish

ultimately, these weren't addressed at the time of issue closing as the "main intent" of this issue has been accomplished. A.K.A.: "make docs easier/faster to publish". Context was added, here, in the event that we would like to re-up this issue or related work in the future.

[sam-heilbron]

Spoke with @Nadine2016 and @nfuden

The plan to migrate docs maintenance out of this repo is delayed. As a result, it would help the docs team a lot to have tests not run on docs changes:

add the ability to skip CI -- the idea was that we could add a comment directive/github tag/changelog directive to stop CI from taking place, thus enabling faster merges on PRs which didn't warrant such scrutiny. Ex: spelling change/broken link. Gloo Mesh already has a [useful, working solution](https://github.com/solo-io/gloo-mesh-enterprise/blob/main/.github/workflows/add-skipci-label.yaml) that can be copied, if desired

Reopening.

New definition of done, is having an ability to skip tests on a docs PR. Clearly outlined and docs team familiar with how to use it and has verified it.

[sam-heilbron]

The ability to skip CI for docs PRs was introduced with https://github.com/solo-io/gloo/pull/8307