ci(docs): generate documentation from policy definition (#849)

Generate within CI the whole documentation for supported policies

------
UDENG-1450

.github/workflows/policy-builds-fail.md

@@ -0,0 +1,5 @@
+---
+title: Update supported policies to ADMX/L and docs failed
+labels: bug, jira
+---
+Failed to update ADMX/L and docs files for ADSys. Please take a look at the run output in {{ env.RUN_URL }}.

.github/workflows/adm-builds.yaml → .github/workflows/policy-builds.yaml

@@ -1,12 +1,12 @@
-name: Update admx and adml templates
+name: Update supported policies to ADMX/L and docs
 on:
   push:
     branches:
       - '**' # Ignore tag push, but take any branch
     paths:
       - 'cmd/admxgen/**'
       - 'internal/ad/admxgen/**'
-      - '.github/workflows/adm-builds.yaml'
+      - '.github/workflows/policy-builds.yaml'
   schedule:
     - cron: '42 0 * * *'
 
@@ -163,10 +163,49 @@ jobs:
           path: Ubuntu.adm*
           if-no-files-found: error
 
-  integrate-ad:
-    name: Integrate AD in current git tree
+  generate-doc:
+    name: Merge keys to generated documentation
     runs-on: ubuntu-latest
-    needs: generate-ad
+    needs: collect-releases
+    steps:
+      - name: Install needed binaries
+        run: |
+          sudo apt-get update
+          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y distro-info
+      - name: Download all available artifacts
+        uses: actions/download-artifact@v3
+        with:
+          path: artifacts
+      - name: Display structure of downloaded files
+        run: |
+          set -eu
+
+          target=$(ubuntu-distro-info -r --supported | cut -d" " -f1)
+          mkdir wanted/
+          for f in $(find artifacts/policies-*/ -type f); do
+            for wanted in ${target}; do
+              if [ $(basename $f) != ${wanted}.yaml ]; then
+                continue
+              fi
+              cp $f wanted/
+            done
+          done
+          chmod +x artifacts/admxgen/admxgen
+          artifacts/admxgen/admxgen doc artifacts/admxgen/cmd/admxgen/defs/categories.yaml wanted/ generated-docs/
+          ls -R
+      - name: Upload adm template files
+        uses: actions/upload-artifact@v3
+        with:
+          name: generated-docs
+          path: generated-docs/*
+          if-no-files-found: error
+
+  integrate:
+    name: Integrate policy changes in current git tree
+    runs-on: ubuntu-latest
+    needs:
+      - generate-ad
+      - generate-doc
     steps:
       - uses: actions/checkout@v4
       - name: Download adm template files for "all"
@@ -179,9 +218,14 @@ jobs:
         with:
           name: adm-LTS
           path: policies/Ubuntu/lts-only
-      - name: Copy admx and adml to git
+      - name: Download generated documentation
+        uses: actions/download-artifact@v3
+        with:
+          name: generated-docs
+          path: docs/reference/policies/
+      - name: Add generated files to git
         run: |
-          git add policies/
+          git add policies/ docs/reference/policies/
       - name: Get output branch for branch name
         id: get-branch-name
         shell: bash
@@ -192,15 +236,15 @@ jobs:
           commit-message: Refresh policy definition files
           title: Refresh policy definition files
           labels: policies, automated pr
-          body: "[Auto-generated pull request](https://github.com/ubuntu/adsys/actions/workflows/adm-builds.yaml) by GitHub Action"
+          body: "[Auto-generated pull request](https://github.com/ubuntu/adsys/actions/workflows/policy-builds.yaml) by GitHub Action"
           branch: auto-update-policydefinitions-${{ steps.get-branch-name.outputs.branch }}
           token: ${{ secrets.GITHUB_TOKEN }}
           delete-branch: true
 
   open-issue-on-fail:
     name: Open issue on failure
     runs-on: ubuntu-latest
-    needs: integrate-ad
+    needs: integrate
     if: ${{ failure() }}
     steps:
       - uses: actions/checkout@v4
@@ -210,6 +254,6 @@ jobs:
           RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
-          filename: .github/workflows/adm-builds-fail.md
+          filename: .github/workflows/policy-builds-fail.md
           search_existing: open
           update_existing: true

cmd/admxgen/defs/mount.yaml

@@ -48,7 +48,7 @@
 
     If the tag is added, the mount will require Kerberos authentication in order to occur.
 
-    The supported protocols / filsystems are the same as the ones supported by the mount command.
+    The supported protocols / file systems are the same as the ones supported by the mount command.
     They are listed on the mount man page on https://man7.org/linux/man-pages/man8/mount.8.html
     It's up to the user to ensure that the requested protocols are valid and supported and that the shared directories have the correct configuration for the requested connection.
   elementtype: "multiText"

cmd/admxgen/defs/proxy.yaml

@@ -79,11 +79,11 @@
     * Not configured: A setting declared higher in the GPO hierarchy will be used if available.
   type: "proxy"
 - key: "/proxy/auto"
-  displayname: "Autoconfiguration URL"
+  displayname: "Auto-configuration URL"
   explaintext: |
-    Declare system-wide proxy autoconfiguration URL.
+    Declare system-wide proxy auto-configuration URL.
 
-    Autoconfiguration URLs are always prioritzed over manual proxy settings, meaning that if all proxy options are set, the GPO client will enable automatic proxy configuration for supported backends. An empty value will remove previously set settings of the same type.
+    Auto-configuration URLs are always prioritized over manual proxy settings, meaning that if all proxy options are set, the GPO client will enable automatic proxy configuration for supported backends. An empty value will remove previously set settings of the same type.
   elementtype: "text"
   release: "any"
   note: |

cmd/admxgen/defs/scripts.yaml

@@ -18,7 +18,7 @@
 - key: "/shutdown"
   displayname: "Shutdown scripts"
   explaintext: |
-    Define scripts that are executed on machine poweroff.
+    Define scripts that are executed on machine power off.
     Those scripts are ordered, one by line, and relative to SYSVOL/ubuntu/scripts/ directory.
     Scripts from this GPO will be appended to the list of scripts referenced higher in the GPO hierarchy.
   elementtype: "multiText"

docs/.custom_wordlist.txt

@@ -8,15 +8,18 @@ ADSys
 adsysctl
 adsysd
 adwatchd
+ALS
 apparmor
 AppArmor
 AppArmor's
 autocompletion
 autoenroll
 autoenrollment
 autoload
+automount
 backend
 backends
+boolean
 CAs
 CEP
 CES
@@ -25,23 +28,30 @@ compinit
 config
 constructiveCAs
 CSR
+dac
 dconf
+dialogs
 dir
 Dropdown
+dropdownList
 enrolment
 erroring
 executables
 fpath
 FQDN
 GDM
+gdm
 GPL
 GPO
 gpolist
 GPOs
 GPT
 GSettings
 GVfs
+gvfs
+HOMEDIRS
 html
+http
 https
 idempotency
 IIS
@@ -53,20 +63,39 @@ ip
 Jira
 kerberos
 Kerberos
+krb
 LDAP
 lifecycle
+linux
+localhost
+lockdown
+LockDown
 LTS
 MacOS
 macOS
+manpages
 multiline
+multiText
+nameservice
+nfs
 OpenLDAP
 OU
 OUs
+plymouth
+png
 polkit
 powershell
 PowerShell
+Px
+rb
 readthedocs
 runscripts
+setgid
+setuid
+smartcard
+smartcards
+smb
+su
 sss
 sssd
 SSSD
@@ -79,20 +108,30 @@ syntaxes
 systemd
 systemd's
 sysvol
+tc
 TDB
 TODO
+toolkits
 toolset
 Transactional
+tunables
 txt
 ubuntu
 Unix
 unmonitoring
 unmount
 unmounting
 Unmounting
+unescaped
+uri
+URI
+URIs
+usr
 unticking
 vendoring
 Winbind
+wm
+xauth
 yaml
 zsh
 zshrc

docs/reference/index.md

@@ -30,6 +30,16 @@ adsysd<adsysd-cli>
 adwatchd<adwatchd-cli>
 ```
 
+```{grid-item}
+## Supported policies
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+policies/index
+```
+
 ````
 
 ## Supported releases

docs/reference/policies/Computer Policies/Ubuntu/Client management/Computer Scripts/shutdown.md

@@ -0,0 +1,30 @@
+# Shutdown scripts
+
+Define scripts that are executed on machine power off.
+Those scripts are ordered, one by line, and relative to SYSVOL/ubuntu/scripts/ directory.
+Scripts from this GPO will be appended to the list of scripts referenced higher in the GPO hierarchy.
+
+
+- Type: scripts
+- Key: /shutdown
+
+Note: -
+ * Enabled: The scripts in the text entry are executed at shutdown time.
+ * Disabled: The scripts will be skipped.
+ The set of scripts are per boot, and refreshed only on new boot of the machine.
+
+
+Supported on Ubuntu 20.04, 22.04, 23.04, 23.10.
+
+An Ubuntu Pro subscription on the client is required to apply this policy.
+
+
+
+<span style="font-size: larger;">**Metadata**</span>
+
+| Element      | Value            |
+| ---          | ---              |
+| Location     | Computer Policies -> Ubuntu -> Client management -> Computer Scripts -> Shutdown scripts    |
+| Registry Key | Software\Policies\Ubuntu\scripts\shutdown         |
+| Element type | multiText |
+| Class:       | Machine       |

docs/reference/policies/Computer Policies/Ubuntu/Client management/Computer Scripts/startup.md

@@ -0,0 +1,30 @@
+# Startup scripts
+
+Define scripts that are executed on machine boot, once the GPO is downloaded.
+Those scripts are ordered, one by line, and relative to SYSVOL/ubuntu/scripts/ directory.
+Scripts from this GPO will be appended to the list of scripts referenced higher in the GPO hierarchy.
+
+
+- Type: scripts
+- Key: /startup
+
+Note: -
+ * Enabled: The scripts in the text entry are executed at startup time.
+ * Disabled: The scripts will be skipped.
+ The set of scripts are per boot, and refreshed only on new boot of the machine.
+
+
+Supported on Ubuntu 20.04, 22.04, 23.04, 23.10.
+
+An Ubuntu Pro subscription on the client is required to apply this policy.
+
+
+
+<span style="font-size: larger;">**Metadata**</span>
+
+| Element      | Value            |
+| ---          | ---              |
+| Location     | Computer Policies -> Ubuntu -> Client management -> Computer Scripts -> Startup scripts    |
+| Registry Key | Software\Policies\Ubuntu\scripts\startup         |
+| Element type | multiText |
+| Class:       | Machine       |

docs/reference/policies/Computer Policies/Ubuntu/Client management/Power Management/ambient-enabled.md

@@ -0,0 +1,22 @@
+# Enable the ALS sensor
+
+If the ambient light sensor functionality is enabled.
+
+- Type: dconf
+- Key: /org/gnome/settings-daemon/plugins/power/ambient-enabled
+- Default: true
+
+Note: default system value is used for "Not Configured" and enforced if "Disabled".
+
+Supported on Ubuntu 20.04, 22.04, 23.04, 23.10.
+
+
+
+<span style="font-size: larger;">**Metadata**</span>
+
+| Element      | Value            |
+| ---          | ---              |
+| Location     | Computer Policies -> Ubuntu -> Client management -> Power Management -> Enable the ALS sensor    |
+| Registry Key | Software\Policies\Ubuntu\dconf\org\gnome\settings-daemon\plugins\power\ambient-enabled         |
+| Element type | boolean |
+| Class:       | Machine       |