Version the documentation for all tools

[joaopapereira]

Implements: https://github.com/vmware-tanzu/carvel/tree/develop/proposals/carvel/001-maintain-documentation

In this PR:

• Script to easily release a new version of the documentation
• Version the documentation
  • kapp
  • kapp-controller
  • imgpkg
  • kbld
  • ytt
  • vendir
• Github action that will run and fail when documentation for a version is updated
• Prepare the website for versioning

Not included on this PR:

• Update our release process to generate the documentation
• Update the Checklist list for the release to ensure the new documentation is generated
• Algolia setup

[pivotaljohn]

We're hashing out the pros and cons of having the latest reference baked into the URL vs. having a specific version.

latest in the URL means:

• that links between tools remain valid even as one tool's (e.g. kapp-controller) documentation references another tool's docs (e.g. ytt);
• links from outside-of-Carvel documentation/bookmarks will break when pages within the docs move in subsequent versions.

Moving into "draft" until we work that out.

[jonasrosland]

I think you might need to identify the multiple projects here.
Can you try changing this to something like:

 {{ $latest-ytt   := site.Params.ytt.version_latest }}
 {{ $latest-imgpkg   := site.Params.imgpkg.version_latest }}

/ytt/docs/         /ytt/docs/{{ $latest-ytt }}
/imgpkgdocs/         /ytt/docs/{{ $latest-ytt }}

[pivotaljohn]

This is fantastic!
Bonus points for providing the workflow hook that detects changes in "frozen" docs!! 👍🏻

There are multiple incompatible versions of yq. The release-docs.sh script fails with the version of yq that wraps jq.

Suggestions below to avoid any such problems by using ytt to pluck values from a YAML.

[gcheadle-vmware]

Since the version drop down list is located at the top of the table of contents, it would be nice to keep that left sidebar fixed, and have it scroll independently from the documentation. There is an issue https://github.com/vmware-tanzu/carvel/issues/324, if we would like to prioritize that work.

[praveenrewar]

LGTM!

[praveenrewar]

I wonder why git thinks these 2 lines are different 🤔

[pivotaljohn]

Thanks for pulling this together, @joaopapereira. It's not just another PR, it's the equivalent of sweeping up a whole section of the workshop and making it ship-shape. 🙏🏻