Skip to content
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

Merged
merged 13 commits into from
Nov 20, 2024

Conversation

jdob
Copy link
Contributor

@jdob jdob commented Nov 19, 2024

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:

  • If a code block is going to use attribute substitution, the block must have the subs="attributes" annotation.
  • If such a code block also contains certain characters (in particular, < 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.
  • I'm debating if versions.adoc will have attributes for the component versions themselves in addition to the chart versions. For example, the Longhorn version is 1.7.1 but the chart version is 104.2.0+up1.7.1 (yuck). This may make sense to include in the release manifest, or they may be manually entered into versions.adoc. We'll see how the conversations with the manifest engineers go.

@jdob jdob requested a review from hardys November 19, 2024 21:08
:version-kubernetes-rke2: v1.30.5+rke2r1

:version-operatingsystem: 6.0

Copy link
Contributor Author

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.

Copy link
Contributor

@hardys hardys left a 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!

@jdob jdob merged commit 4696e16 into suse-edge:main Nov 20, 2024
1 check passed
This was referenced Nov 20, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants