Declare Python 3.12 support; test with Python 3.12; improve node.js d…

…ependency handling and CSS building CI (#255)

* List Python 3.12 as supported, and run tests with it.

* Make sure that the CSS build doesn't change any files.

* Add changelog fragment.

* Standardize node.js requirements.

* Use Dependabot to update node.js packages.

* Add instructions in case CI fails.

* Add licensing information.

* Don't pass -v to nox when linting.

.github/dependabot.yml

@@ -9,3 +9,7 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+  - package-ecosystem: "npm"
+    directory: "/src/sphinx_antsibull_ext/css/"
+    schedule:
+      interval: "weekly"

.github/workflows/antsibull-docs.yml

@@ -30,7 +30,7 @@ jobs:
           - '--use-current --sphinx-theme sphinx_rtd_theme'
           - '--no-indexes --squash-hierarchy --intersphinx ansible7:https://docs.ansible.com/ansible/6/ community.crypto --collection-version 2.0.0'
         python:
-          - '3.11'
+          - '3.12'
         antsibull_core_ref:
           - main
           - "stable-2"
@@ -40,7 +40,7 @@ jobs:
           - options: '--use-current --use-html-blobs --no-breadcrumbs community.crypto community.docker'
             python: '3.9'
           - options: '--use-current --output-format simplified-rst community.crypto community.docker'
-            python: '3.10'
+            python: '3.11'
 
     steps:
       - name: Check out antsibull-docs
@@ -166,10 +166,10 @@ jobs:
           repository: ansible-community/antsibull-docs-parser
           path: antsibull-docs-parser
 
-      - name: Set up Python 3.11
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install dependencies
         run: |
@@ -224,10 +224,10 @@ jobs:
           repository: ansible-community/antsibull-docs-parser
           path: antsibull-docs-parser
 
-      - name: Set up Python 3.11
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install dependencies
         run: |

.github/workflows/build-css.yml

@@ -34,9 +34,20 @@ jobs:
 
       - name: Install dependencies
         run: |
-          npm install -g sass autoprefixer cssnano postcss postcss-cli
+          npm clean-install
+        working-directory: ./src/sphinx_antsibull_ext/css
 
       - name: Build CSS
         run: |
           ./build.sh
         working-directory: ./src/sphinx_antsibull_ext/css
+
+      - name: Make sure no files were changed
+        run: |
+          CHANGED="$(git status --porcelain=v1 --untracked=normal)"
+          if [ "${CHANGED}" != "" ]; then
+            echo "Found changed files:"
+            echo "${CHANGED}"
+            echo "In case you changed the SCSS source files, you need to run './build.sh' (after running 'npm install') in src/sphinx_antsibull_ext/css"
+            exit 1
+          fi

.github/workflows/nox.yml

@@ -46,9 +46,9 @@ jobs:
       - name: Setup nox
         uses: wntrblm/nox@2024.03.02
         with:
-          python-versions: "3.11"
+          python-versions: "3.12"
       - run: |
-          nox -v -e lint
+          nox -e lint
   nox-test:
     runs-on: ubuntu-latest
     defaults:
@@ -72,7 +72,7 @@ jobs:
       - name: Setup nox
         uses: wntrblm/nox@2024.03.02
         with:
-          python-versions: "3.9, 3.10, 3.11"
+          python-versions: "3.9, 3.10, 3.11, 3.12"
       - name: Run unit tests
         run: |
           nox -v -e test

README.md

@@ -84,14 +84,10 @@ cd sphinx_antsibull_ext/css/
 ./build-css.sh
 ```
 
-For this to work, you need to make sure that `sassc` and `postcss` are on your path and that the autoprefixer and nanocss modules are installed:
+For this to work, you need to install some Node.js dependencies:
 
 ```console
-# Debian:
-apt-get install sassc
-
-# PostCSS, autoprefixer and cssnano require nodejs/npm:
-npm install -g autoprefixer cssnano postcss postcss-cli
+npm clean-install
 ```
 
 ## Creating a new release:

changelogs/fragments/255-python-3.12.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "Declare support for Python 3.12 (https://github.com/ansible-community/antsibull-docs/pull/255)."

noxfile.py

@@ -69,7 +69,7 @@ def other_antsibull(
     return to_install
 
 
-@nox.session(python=["3.9", "3.10", "3.11"])
+@nox.session(python=["3.9", "3.10", "3.11", "3.12"])
 def test(session: nox.Session):
     install(
         session,
@@ -79,7 +79,7 @@ def test(session: nox.Session):
     )
     covfile = Path(session.create_tmp(), ".coverage")
     more_args = []
-    if session.python == "3.11":
+    if session.python in {"3.11", "3.12"}:
         more_args.append("--error-for-skips")
     session.run(
         "pytest",

pyproject.toml

@@ -20,6 +20,7 @@ classifiers = [
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "Typing :: Typed",
 ]
 requires-python = ">=3.9"

src/sphinx_antsibull_ext/css/.gitignore

@@ -0,0 +1,5 @@
+# Copyright (c) Ansible and contributors
+# GNU General Public License v3.0+ (see https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+/node_modules

src/sphinx_antsibull_ext/css/build.sh

@@ -3,16 +3,16 @@
 # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-SASS=${SASS_COMPILER:-$(which sass)}
-POSTCSS=${POSTCSS:-$(which postcss)}
+SASS=${SASS_COMPILER:-node_modules/.bin/sass}
+POSTCSS=${POSTCSS:-node_modules/.bin/postcss}
 
-if [ "${SASS}" == "" ]; then
-    echo "Need 'sass' on path. You can install sass with 'npm install sass'."
+if [ ! -x "${SASS}" ]; then
+    echo "${SASS} is not executable. Did you run 'npm install'?"
     exit -1
 fi
 
-if [ "${POSTCSS}" == "" ]; then
-    echo "Need 'postcss' on path. You can install postcss and the required plugins with 'npm install autoprefixer cssnano postcss postcss-cli'."
+if [ ! -x "${POSTCSS}" ]; then
+    echo "${POSTCSS} is not executable. Did you run 'npm install'?"
     exit -1
 fi