document undocumented settings, document settings vs. environment variables

.github/allow-documented-unused.txt

@@ -0,0 +1,9 @@
+DB_URL
+PLUGIN_AUTH_LDAP
+PLUGIN_AUTH_OIDC
+PLUGIN_FREEIPA
+PLUGIN_IQUOTA
+PLUGIN_LDAP_USER_SEARCH
+PLUGIN_PROJECT_OPENLDAP
+PLUGIN_SLURM
+PLUGIN_XDMOD

.github/workflows/ci.yml

@@ -31,3 +31,48 @@ jobs:
 
       - name: Run tests
         run: uv run coldfront test
+
+  check_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: apt install -y ripgrep
+        run: |
+          echo "set man-db/auto-update false" | sudo debconf-communicate
+          sudo dpkg-reconfigure man-db
+          sudo apt install -y ripgrep
+      # a setting "foo" exists if there is any use of `import_from_settings("foo")` or {% settings_value "foo" %}
+      # note about quotations: '\bsettings_value[ ]+["'"'"']([A-Z_]+)' -> \bsettings_value[ ]+["']([A-Z_]+)
+      # import_from_settings('foo') is not considered because ruff format ensures double quotes are used
+      # `grep .` filters out empty lines
+      - name: gather list of settings used
+        run: |
+          (
+            rg -INU '\bimport_from_settings\([\s\n]*"([A-Z_]+)' -or '$1' .
+            rg -IN '\bsettings_value[ ]+["'"'"']([A-Z_]+)' -or '$1' .
+          ) | grep . | sort -u | tee -a /tmp/settings.txt
+      # an env var "foo" exists if there is any use of `ENV.bool("foo")` or `ENV.int("foo")` or `ENV.list("foo")` or ...
+      - name: gather list of environment variables used
+        run: rg -INU '\bENV\.[a-z]+\([\s\n]*"([A-Z_]+)' -or '$1' . | grep . | sort -u | tee /tmp/envvars.txt
+      # a setting or environment variable is documented if it is found in the leftmost column of a table in docs/pages/config.md
+      - name: gather list of settings and environment variables documented
+        run: rg '^\|[ ]*`?([A-Z_]{2,})' -or '$1' docs/pages/config.md | sort -u | tee /tmp/documented.txt
+      - name: check that all settings used are documented
+        run: |
+          if grep -vFx --file=/tmp/documented.txt /tmp/settings.txt; then
+            echo "the settings above must be added to the documentation!"
+            exit 1
+          fi
+      - name: check that all environment variables used are documented
+        run: |
+          if grep -vFx --file=/tmp/documented.txt /tmp/envvars.txt; then
+            echo "the environment variables above must be added to the documentation!"
+            exit 1
+          fi
+      - name: check that all settings and environment variables documented are used
+        run: |
+          if grep -vFx --file=/tmp/settings.txt --file=/tmp/envvars.txt --file=.github/allow-documented-unused.txt /tmp/documented.txt; then
+            echo "the environment variables above are documented but never used!"
+            echo "to silence this error for a specific variable, add it to the file '.github/allow-documented-unused.txt'."
+            exit 1
+          fi

CONTRIBUTING.md

@@ -65,3 +65,10 @@ If your code is failing linting checks but you you have a valid reason to leave
 You can also use Ruff to check formatting using `uv run ruff format --check` and automatically fix formatting errors with `uv run ruff format`.
 
 If your code is failing formatting checks but you have a valid reason to leave it unchanged, you can suppress warnings for a specific block of code by enclosing it with the comments `# fmt: off` and `# fmt: on`. These comments work at the statement level so placing them inside of expressions will not have any effect. 
+
+#### Documentation
+
+All settings and environment variables used should be present in [docs/pages/config.md](docs/pages/config.md).
+A "setting used" is the 1st argument to any `import_from_settings()` function call or `{% setting_value %}` jinja2 macro usage.
+An "environment variable used" is the 1st argument to any `ENV` function call (ex: `ENV.bool()`)
+Setting names and environment variable names should contain capital letters and underscores only.