Move V2 API docs to Github Pages

pivotalgeorge commented 2 weeks ago

Thanks for contributing to cloud_controller_ng. To speed up the process of reviewing your pull request please provide us with:

A short explanation of the proposed change: Serve the V2 API docs as static GitHub Pages assets, deployed via GitHub Actions
An explanation of the use cases your change solves As part of the VMware->Broadcom migration, the infrastructure hosting the current v2 apidocs is being replaced. This provides an opportunity to sunset unneeded apps, lowering the project's maintenance & support burden.
[x] I have reviewed the contributing guide
[x] I have viewed, signed, and submitted the Contributor License Agreement
[x] I have made this pull request to the main branch
[x] I have run all the unit tests using bundle exec rake
[ ] I have run CF Acceptance Tests
- this PR makes no changes to CAPI behavior

pivotalgeorge commented 1 week ago

Yep, v3 is already deploying to GitHub Pages, and it seems like a switch to GitHub Actions is in-progress. The corresponding change to capi-ci would be to remove doc-publishing behavior.

As far as triggering on tags/releases, that sounds good, but this repo (CCNG) doesn't use tags. I'm assuming you mean triggering on releases in capi-release, right?

sethboyles commented 1 week ago

As far as triggering on tags/releases, that sounds good, but this repo (CCNG) doesn't use tags. I'm assuming you mean triggering on releases in capi-release, right?

I think that's what we'd have to do. Is that even possible?

evanfarrar commented 1 week ago

As far as triggering on tags/releases, that sounds good, but this repo (CCNG) doesn't use tags. I'm assuming you mean triggering on releases in capi-release, right?

I think that's what we'd have to do. Is that even possible?

maybe the github actions should run in capi-release? we tag / release in capi release

moleske commented 1 week ago

Could tag this repo with the version on the commit that is included in the capi release version. Then wouldn't have to move the docs. Also fine with moving the docs and action to capi release so only one place has to be tagged.

Might also be a way to trigger actions across repos but that seems unnecessarily complicated.

I was mostly asking cause I noticed trigger was just on main/gh-pages. Which may be just fine as long as new versions are created properly. I'm out of practice on how the old docs did all this cause "it just worked." So triggering off of tags may not be needed if when a new version is created the pipeline just makes the new version, e.g. on commits like this, or this, or this. And doc changes to main that aren't new versions just update the release candidate version.

I don't have strong feelings was just curious what the plan is as it is clear vmware/broadcom from George's message is uninterested in hosting the existing docs site (which I'm assuming includes hosting v3 in addition to the v2 George mentions in this pr). Also don't think any of the above needs to block merging this pr since it has manual triggers and all that for folks to test out first before letting the bots run it

philippthun commented 1 week ago

Yep, v3 is already deploying to GitHub Pages, and it seems like a switch to GitHub Actions is in-progress. The corresponding change to capi-ci would be to remove doc-publishing behavior.

We did not change the v3 docs build process, we only moved the script over to capi-ci - and did some improvements like getting rid of git ssh. So both, release candidate and final docs, are still created by jobs in the Concourse pipeline and the GitHub action deploy_v3_docs is only used to upload the results (the previously used mechanism was discontinued by GitHub beginning of July).

pivotalgeorge commented 1 week ago

@philippthun, thanks for the clarification. This PR is just about v2 docs. The Concourse vs. Github Actions decision will be relevant for v3, but as v3 docs are in GH-pages, they will not be impacted by the current impending shutdown.

@moleske

Could tag this repo with the version on the commit that is included in the capi release version

is picking-up version info from config/version_v2 insufficient?

philippthun commented 1 week ago

This PR is just about v2 docs.

Okay, I see. Would you mind removing the file .github/workflows/gh_pages_docs_v3.yml from this PR?

pivotalgeorge commented 1 week ago

@sethboyles & @evanfarrar — to followup on the capi-release triggering conversation:

I created a draft PR on the capi-release side: https://github.com/cloudfoundry/capi-release/pull/438 an example triggered run is #12 - shows up as triggered by me since the secret was set to an access token tied to my account, but In Production™ this would be a bot account.

@moleske would this address your original concern?

pivotalgeorge commented 1 week ago

~~Since today is the last day for the PCF env hosting v2 docs, I say we merge this in to avoid downtime~~ On second thought, seems like we won't be able to assign the v2 (or any) custom domain to GitHub pages here, since the v3 docs domain is already bound. + thanks @sethboyles for doing a once-over w me before shipping & spotting this

pivotalgeorge commented 1 week ago

After discussing with @sethboyles and @Gerg: Moving the v2 workflow to capi-release. see https://github.com/cloudfoundry/capi-release/pull/440

cloudfoundry / cloud_controller_ng

Move V2 API docs to Github Pages #3874