Merge pull request coreos#460 from bgilbert/docgen

Automatically generate spec docs
prestist · Apr 25, 2023 · 65e7f02 · 65e7f02
2 parents baf6e7d + af06947
commit 65e7f02
Show file tree

Hide file tree

Showing 44 changed files with 2,950 additions and 16 deletions.
diff --git a/.github/ISSUE_TEMPLATE/stabilize-checklist.md b/.github/ISSUE_TEMPLATE/stabilize-checklist.md
@@ -29,8 +29,8 @@ This checklist describes bumping the Ignition spec version, `base` version, and
 
 ## Update docs
 
-- [ ] Copy the `C-exp` spec doc to `C+1-exp`. Update the header and the version numbers in the description of the `version` field.
-- [ ] Rename the `C-exp` spec doc to `C`. Update the header, delete the experimental config warning, and update the version numbers in the description of the `version` field. Update the `nav_order` to one less than the previous stable release.
+- [ ] Update `internal/doc/main.go` to add the new stable spec and reference the new experimental spec in `generate()`.
+- [ ] Run `generate` to regenerate spec docs.
 - [ ] Update `docs/specs.md`.
 - [ ] Update `docs/upgrading-*.md` for the new spec version. Copy the relevant section from Ignition's `doc/migrating-configs.md`, convert the configs to Butane configs, convert field names to snake case, and update wording as needed. Add subsections for any new Butane-specific features.
 - [ ] Note the stabilization in `docs/release-notes.md`, following the format of previous stabilizations. Drop the `-exp` version suffix from any notes for the upcoming release.
diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml
@@ -42,3 +42,23 @@ jobs:
       with:
         version: v1.51.1
         args: -E=gofmt --timeout=30m0s
+  regenerate:
+    name: Regenerate docs
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v3
+    - name: Set up Go 1.x
+      uses: actions/setup-go@v4
+      with:
+        go-version: 1.20.x
+    - name: Regenerate spec docs
+      run: ./generate
+    - name: Check whether spec docs are current
+      run: |
+        if [ -n "$(git status --porcelain docs)" ]; then
+          echo "Found local changes after regenerating:"
+          git --no-pager diff --color=always docs
+          echo "Rerun './generate'."
+          exit 1
+        fi
diff --git a/config/util/util.go b/config/util/util.go
@@ -36,7 +36,7 @@ import (
 )
 
 var (
-	snakeRe = regexp.MustCompile("([A-Z])")
+	snakeRe = regexp.MustCompile("(MiB|[A-Z])")
 )
 
 // Misc helpers
@@ -204,16 +204,16 @@ func snakePath(p path.ContextPath) path.ContextPath {
 	ret := path.New(p.Tag)
 	for _, part := range p.Path {
 		if str, ok := part.(string); ok {
-			ret = ret.Append(snake(str))
+			ret = ret.Append(Snake(str))
 		} else {
 			ret = ret.Append(part)
 		}
 	}
 	return ret
 }
 
-// snake converts from camelCase (not CamelCase) to snake_case
-func snake(in string) string {
+// Snake converts from camelCase (not CamelCase) to snake_case
+func Snake(in string) string {
 	return strings.ToLower(snakeRe.ReplaceAllString(in, "_$1"))
 }
 

diff --git a/config/util/util_test.go b/config/util/util_test.go
@@ -52,8 +52,8 @@ func TestSnake(t *testing.T) {
 
 	for i, test := range tests {
 		t.Run(fmt.Sprintf("%d", i), func(t *testing.T) {
-			if snake(test.in) != test.out {
-				t.Errorf("expected %q got %q", test.out, snake(test.in))
+			if Snake(test.in) != test.out {
+				t.Errorf("expected %q got %q", test.out, Snake(test.in))
 			}
 		})
 	}

diff --git a/docs/config-fcos-v1_0.md b/docs/config-fcos-v1_0.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: Fedora CoreOS v1.0.0
 parent: Configuration specifications
 nav_order: 49

diff --git a/docs/config-fcos-v1_1.md b/docs/config-fcos-v1_1.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: Fedora CoreOS v1.1.0
 parent: Configuration specifications
 nav_order: 48

diff --git a/docs/config-fcos-v1_2.md b/docs/config-fcos-v1_2.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: Fedora CoreOS v1.2.0
 parent: Configuration specifications
 nav_order: 47

diff --git a/docs/config-fcos-v1_3.md b/docs/config-fcos-v1_3.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: Fedora CoreOS v1.3.0
 parent: Configuration specifications
 nav_order: 46

diff --git a/docs/config-fcos-v1_4.md b/docs/config-fcos-v1_4.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: Fedora CoreOS v1.4.0
 parent: Configuration specifications
 nav_order: 45

diff --git a/docs/config-fcos-v1_5.md b/docs/config-fcos-v1_5.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: Fedora CoreOS v1.5.0
 parent: Configuration specifications
 nav_order: 44

diff --git a/docs/config-fcos-v1_6-exp.md b/docs/config-fcos-v1_6-exp.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: Fedora CoreOS v1.6.0-experimental
 parent: Configuration specifications
 nav_order: 50

diff --git a/docs/config-flatcar-v1_0.md b/docs/config-flatcar-v1_0.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: Flatcar v1.0.0
 parent: Configuration specifications
 nav_order: 99

diff --git a/docs/config-flatcar-v1_1.md b/docs/config-flatcar-v1_1.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: Flatcar v1.1.0
 parent: Configuration specifications
 nav_order: 98

diff --git a/docs/config-flatcar-v1_2-exp.md b/docs/config-flatcar-v1_2-exp.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: Flatcar v1.2.0-experimental
 parent: Configuration specifications
 nav_order: 100

diff --git a/docs/config-openshift-v4_10.md b/docs/config-openshift-v4_10.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: OpenShift v4.10.0
 parent: Configuration specifications
 nav_order: 147

diff --git a/docs/config-openshift-v4_11.md b/docs/config-openshift-v4_11.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: OpenShift v4.11.0
 parent: Configuration specifications
 nav_order: 146

diff --git a/docs/config-openshift-v4_12.md b/docs/config-openshift-v4_12.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: OpenShift v4.12.0
 parent: Configuration specifications
 nav_order: 145

diff --git a/docs/config-openshift-v4_13.md b/docs/config-openshift-v4_13.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: OpenShift v4.13.0
 parent: Configuration specifications
 nav_order: 144

diff --git a/docs/config-openshift-v4_14-exp.md b/docs/config-openshift-v4_14-exp.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: OpenShift v4.14.0-experimental
 parent: Configuration specifications
 nav_order: 150

diff --git a/docs/config-openshift-v4_8.md b/docs/config-openshift-v4_8.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: OpenShift v4.8.0
 parent: Configuration specifications
 nav_order: 149

diff --git a/docs/config-openshift-v4_9.md b/docs/config-openshift-v4_9.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: OpenShift v4.9.0
 parent: Configuration specifications
 nav_order: 148

diff --git a/docs/config-r4e-v1_0.md b/docs/config-r4e-v1_0.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: RHEL for Edge v1.0.0
 parent: Configuration specifications
 nav_order: 199

diff --git a/docs/config-r4e-v1_1.md b/docs/config-r4e-v1_1.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: RHEL for Edge v1.1.0
 parent: Configuration specifications
 nav_order: 198

diff --git a/docs/config-r4e-v1_2-exp.md b/docs/config-r4e-v1_2-exp.md
@@ -1,4 +1,6 @@
 ---
+# This file is automatically generated from internal/doc and Ignition's
+# config/doc.  Do not edit.
 title: RHEL for Edge v1.2.0-experimental
 parent: Configuration specifications
 nav_order: 200

diff --git a/generate b/generate
@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+echo "Generating docs..."
+eval $(go env)
+if [ -z ${BIN_PATH+a} ]; then
+	BIN_PATH=${PWD}/bin/$(go env GOARCH)
+fi
+go build -o ${BIN_PATH}/doc internal/doc/main.go
+${BIN_PATH}/doc ${PWD}/docs
diff --git a/go.mod b/go.mod
@@ -6,7 +6,7 @@ require (
 	github.com/clarketm/json v1.17.1
 	github.com/coreos/go-semver v0.3.1
 	github.com/coreos/go-systemd/v22 v22.5.0
-	github.com/coreos/ignition/v2 v2.15.0
+	github.com/coreos/ignition/v2 v2.15.1-0.20230422002549-116c4abed1be
 	github.com/coreos/vcontext v0.0.0-20230201181013-d72178a18687
 	github.com/spf13/pflag v1.0.6-0.20210604193023-d5e0c0615ace
 	github.com/stretchr/testify v1.8.2
@@ -15,10 +15,12 @@ require (
 )
 
 require (
-	github.com/aws/aws-sdk-go v1.44.204 // indirect
+	github.com/aws/aws-sdk-go v1.44.244 // indirect
 	github.com/coreos/go-json v0.0.0-20230131223807-18775e0fb4fb // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/kr/pretty v0.3.1 // indirect
+	github.com/mitchellh/copystructure v1.2.0 // indirect
+	github.com/mitchellh/reflectwalk v1.0.2 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 // indirect
 )
diff --git a/go.sum b/go.sum
@@ -1,5 +1,5 @@
-github.com/aws/aws-sdk-go v1.44.204 h1:7/tPUXfNOHB390A63t6fJIwmlwVQAkAwcbzKsU2/6OQ=
-github.com/aws/aws-sdk-go v1.44.204/go.mod h1:aVsgQcEevwlmQ7qHE9I3h+dtQgpqhFB+i8Phjh7fkwI=
+github.com/aws/aws-sdk-go v1.44.244 h1:QzBWLD5HjZHdRZyTMTOWtD9Pobzf1n8/CeTJB4giXi0=
+github.com/aws/aws-sdk-go v1.44.244/go.mod h1:aVsgQcEevwlmQ7qHE9I3h+dtQgpqhFB+i8Phjh7fkwI=
 github.com/clarketm/json v1.17.1 h1:U1IxjqJkJ7bRK4L6dyphmoO840P6bdhPdbbLySourqI=
 github.com/clarketm/json v1.17.1/go.mod h1:ynr2LRfb0fQU34l07csRNBTcivjySLLiY1YzQqKVfdo=
 github.com/coreos/go-json v0.0.0-20230131223807-18775e0fb4fb h1:rmqyI19j3Z/74bIRhuC59RB442rXUazKNueVpfJPxg4=
@@ -8,8 +8,8 @@ github.com/coreos/go-semver v0.3.1 h1:yi21YpKnrx1gt5R+la8n5WgS0kCrsPp33dmEyHReZr
 github.com/coreos/go-semver v0.3.1/go.mod h1:irMmmIw/7yzSRPWryHsK7EYSg09caPQL03VsM8rvUec=
 github.com/coreos/go-systemd/v22 v22.5.0 h1:RrqgGjYQKalulkV8NGVIfkXQf6YYmOyiJKk8iXXhfZs=
 github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
-github.com/coreos/ignition/v2 v2.15.0 h1:v2fQ6QvkcAF+La5PHHpnpBS1eGZo+LYL1wTOPvDKAcs=
-github.com/coreos/ignition/v2 v2.15.0/go.mod h1:+7BiKurzCFg3P427Ml0wqnKzIuhLimnil6LhFV2DkJM=
+github.com/coreos/ignition/v2 v2.15.1-0.20230422002549-116c4abed1be h1:Eds8BVLAHo3PstuGpdNrSJXx9NLGQaGvLCY/ECez8jg=
+github.com/coreos/ignition/v2 v2.15.1-0.20230422002549-116c4abed1be/go.mod h1:mlxzevcm0yniBnC33SWpjjJJDYQbp58HXzxvSvs2u04=
 github.com/coreos/vcontext v0.0.0-20230201181013-d72178a18687 h1:uSmlDgJGbUB0bwQBcZomBTottKwEDF5fF8UjSwKSzWM=
 github.com/coreos/vcontext v0.0.0-20230201181013-d72178a18687/go.mod h1:Salmysdw7DAVuobBW/LwsKKgpyCPHUhjyJoMJD+ZJiI=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
@@ -23,6 +23,10 @@ github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/mitchellh/copystructure v1.2.0 h1:vpKXTN4ewci03Vljg/q9QvCGUDttBOGBIa15WveJJGw=
+github.com/mitchellh/copystructure v1.2.0/go.mod h1:qLl+cE2AmVv+CoeAwDPye/v+N2HKCj9FbZEVFJRxO9s=
+github.com/mitchellh/reflectwalk v1.0.2 h1:G2LzWKi524PWgd3mLHV8Y5k7s6XUvT0Gef6zxSIeXaQ=
+github.com/mitchellh/reflectwalk v1.0.2/go.mod h1:mSTlrgnPZtwu0c4WaC2kGObEpuNDbx0jmZXqmk4esnw=
 github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=