chore: automatic jimmctl reference documentation

.github/workflows/publish-docs.yaml

@@ -0,0 +1,63 @@
+name: Publish Docs
+
+# This workflow builds jimmctl and generates a markdown formatted
+# documentation reference before converting the doc to rst and 
+# making a PR to the jaas-documentation repo to update the docs.
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v3*'
+
+jobs:
+  publish-jimmctl-docs:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        fetch-tags: true
+    - run: git fetch --tags --force origin # https://github.com/actions/checkout/issues/882 & https://github.com/actions/checkout/issues/290 
+
+    - name: Build jimmctl
+      run: go build ./cmd/jimmctl/
+
+      # Default doc name is documentation.md which can't be changed via flags.
+    - name: Generate docs
+      run: ./jimmctl documentation --out .
+
+    - name: Convert doc to reStructuredText
+      uses: docker://pandoc/core:3.5
+      with:
+        args: "documentation.md -o documentation.rst --wrap=none"
+
+      # We do this because the original doc doesn't have a top level heading.: 
+    - name: Create final doc with title
+      run: |
+        echo "Jimmctl Reference" > jimmctl-reference.rst
+        echo "#################" >> jimmctl-reference.rst
+        echo "" >> jimmctl-reference.rst
+        cat documentation.rst >> jimmctl-reference.rst
+
+    - name: Checkout docs
+      uses: actions/checkout@v4
+      with:
+        repository: 'canonical/jaas-documentation'
+        ref: 'v3'
+        path: ./jaas-documentation
+
+    - name: Update Docs
+      working-directory: ./jaas-documentation
+      run: cp ../jimmctl-reference.rst ./reference/jimmctl.rst
+
+    - name: Create Pull Request
+      uses: peter-evans/create-pull-request@v6
+      with:
+        token: ${{ secrets.JIMM_GO_SDK_PAT }}
+        path: ./jaas-documentation
+        branch: update-jimmctl-${{ github.run_number }}
+        title: Update jimmctl reference doc
+        body: This PR updates the jimmctl reference doc.
+        commit-message: Updated jimmctl reference for release ${{ github.event.ref }}

go.mod

@@ -5,7 +5,7 @@ go 1.23
 // Juju based dependencies
 require (
 	github.com/juju/charm/v12 v12.1.1
-	github.com/juju/cmd/v3 v3.0.16
+	github.com/juju/cmd/v3 v3.1.1
 	github.com/juju/errors v1.0.0
 	github.com/juju/gnuflag v1.0.0
 	github.com/juju/http/v2 v2.0.1

go.sum

@@ -592,6 +592,10 @@ github.com/juju/cmd v0.0.0-20171107070456-e74f39857ca0/go.mod h1:yWJQHl73rdSX4DH
 github.com/juju/cmd/v3 v3.0.0-20220202061353-b1cc80b193b0/go.mod h1:EoGJiEG+vbMwO9l+Es0SDTlaQPjH6nLcnnc4NfZB3cY=
 github.com/juju/cmd/v3 v3.0.16 h1:P/tG4BPtE+MsmECtnFx+KBC8NFi1ESvHbZ8NzMAll1g=
 github.com/juju/cmd/v3 v3.0.16/go.mod h1:lGtDvm2BG+FKnIS8yY/vrhxQNX9imnL6bPIYGSTchuI=
+github.com/juju/cmd/v3 v3.1.0 h1:u8aXkeZI/BWSK310oOVMgFq66odDY7QGbL+hU1wp1OA=
+github.com/juju/cmd/v3 v3.1.0/go.mod h1:lGtDvm2BG+FKnIS8yY/vrhxQNX9imnL6bPIYGSTchuI=
+github.com/juju/cmd/v3 v3.1.1 h1:mhXjnm/tj1uYieTd6zc+lAyCrXsETrD+WdsTI6gAM3c=
+github.com/juju/cmd/v3 v3.1.1/go.mod h1:lGtDvm2BG+FKnIS8yY/vrhxQNX9imnL6bPIYGSTchuI=
 github.com/juju/collections v0.0.0-20200605021417-0d0ec82b7271/go.mod h1:5XgO71dV1JClcOJE+4dzdn4HrI5LiyKd7PlVG6eZYhY=
 github.com/juju/collections v0.0.0-20220203020748-febd7cad8a7a/go.mod h1:JWeZdyttIEbkR51z2S13+J+aCuHVe0F6meRy+P0YGDo=
 github.com/juju/collections v1.0.0/go.mod h1:JWeZdyttIEbkR51z2S13+J+aCuHVe0F6meRy+P0YGDo=