-
Notifications
You must be signed in to change notification settings - Fork 30
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Introduced version attributes to the documentation - Part 1 #495
Conversation
:version-kubernetes-rke2: v1.30.5+rke2r1 | ||
|
||
:version-operatingsystem: 6.0 | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The names of the components below (i.e. everything between version-
and -chart
) come directly from the release manifest, which is why some of them are on the longer side. This enables us to write a tool that generates the attributes below by simply inspecting a release manifest.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks so much for working on this, built locally and I can see the attribute substitutions are working, lgtm!
Currently, the process of updating the documentation is painful due to the sheer number of places that need to have their version numbers updated, such as the overall edge registry version and each individual chart. Asciidoc supports attribute substitution and this PR introduces two files for defining those attributes, as well as migrations for about a third of the overall documentation.
The two files that will contain this sort of volatile information are:
versions.adoc
- Currently, there is a divider in this file. Above the divider is information that we don't have a way to programmatically deduce and will need to manually be updated. Below it are values that can be ripped from a release manifest. After the docs conversion, I'm going to work on a tool that will generate (at very least) the fields below the divider from a given release manifest. I'm going to talk with the release manifest devs to see what else of this data makes sense to include in the manifest to further automate things, but I suspect it'll never completely be derived data.links.adoc
- I pulled out any links that I encountered that are version-specific. I thought about having the URLs derived inline based on the version, but there's no guarantee that these links will remain valid from version to version. The list is short enough that we should verify each of the links per documentation release to ensure they haven't moved.The remainder of the file changes are updating the quickstarts and about half of the component guides to use the attributes. I had a feeling this PR was going to get long with all of those changes (spoiler: it did), so I wanted to get this out there and landed so that subsequent updates I do in the next few days are hopefully smaller.
I think this PR is in a good place to land. However, I may still change some of the attribute names or organization as I see how the rest of the conversion goes, so don't be surprised if a future PR refines some of the attributes themselves. Like I said, I wanted to keep this from being a mountain of a PR, so the results of this PR will be functionally equivalent to what is produced by the docs before it lands, with the rest of the changes coming in the next few days.
Other notes:
subs="attributes"
annotation.<
in my experiences), it must have a second annotation (subs="attributes,specialchars"
) to escape those characters. Otherwise, you'll get obtuse errors about invalid XML. That's why you only see a few code blocks with the longer annotation.versions.adoc
will have attributes for the component versions themselves in addition to the chart versions. For example, the Longhorn version is1.7.1
but the chart version is104.2.0+up1.7.1
(yuck). This may make sense to include in the release manifest, or they may be manually entered intoversions.adoc
. We'll see how the conversations with the manifest engineers go.