Merge pull request saltstack#31 from scriptautomate-bc/update-install-guide-doc

Update pre-commit, nox, and devcontainer standards

Author: scriptautomate-bc

.devcontainer.json

@@ -0,0 +1,11 @@
+FROM bitnami/python:3.13
+
+RUN apt update && apt upgrade -y && apt install vim -y
+
+# Add dev requirements
+ADD requirements.txt /tmp/
+RUN pip3 install -r /tmp/requirements.txt
+RUN rm /tmp/requirements.txt
+
+# Help avoid "unsupported locale setting" in Sphinx
+RUN echo "export LC_ALL=C.UTF-8" > ~/.bashrc

.devcontainer/Dockerfile

@@ -0,0 +1,49 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+{
+	"name": "salt-install-guide",
+
+	// README at: https://github.com/devcontainers/templates/tree/main/src/python
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	// Python container image is needed for running python-based tests (ex. orphaned-content.py)
+	// "image": "mcr.microsoft.com/devcontainers/python:3.13-bookworm",
+
+	"build": {
+		"dockerfile": "Dockerfile"
+	},
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {
+		// node / npm is required for markdownlint-cli2
+		// By default, installs lts version
+		// "ghcr.io/devcontainers/features/node:1": {}
+	// },
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": ""
+
+	// There is also a postStartCommand that executes every time the container starts.
+	// The parameters behave exactly like postCreateCommand, but the commands execute on start rather than create.
+	// "postStartCommand": ""
+
+	// There is also a postAttachCommand that executes every time the container attaches to a workspace.
+	// The parameters behave exactly like postCreateCommand, but the commands execute on a started container after the workspace is available under /workspaces/
+	// "postAttachCommand": {},
+
+	// Configure tool-specific properties.
+	"customizations": {
+		// Configure properties specific to VS Code.
+		"vscode": {
+			// Add the IDs of extensions you want installed when the container is created.
+			"extensions": [
+				// Extension to work with Python
+				"ms-python.python"
+			]
+		}
+	}
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

.devcontainer/devcontainer.json

@@ -34,7 +34,7 @@ jobs:
       - name: Run pre-commit
         run: |
           pip install -U pip setuptools wheel
-          pip install -r requirements-dev.txt
+          pip install -r .devcontainer/requirements.txt
           pre-commit install
           pre-commit run -a -v --color always
       - name: Build docs

requirements-dev.txt .devcontainer/requirements.txtrequirements-dev.txt renamed to .devcontainer/requirements.txt

@@ -29,13 +29,13 @@ repos:
           You must provide list of target files as input in your .pre-commit-config.yaml file.
         files: ^(.*requirements.*\.txt|\.brokignore)$
   - repo: https://github.com/PyCQA/isort
-    rev: "5.13.2"
+    rev: "6.0.1"
     hooks:
       - id: isort
         description: isort is a Python utility / library to sort imports automatically.
         files: ^((noxfile|conf)|docs/.*)\.py$
   - repo: https://github.com/psf/black
-    rev: 24.10.0
+    rev: 25.1.0
     hooks:
       - id: black
         description: Forces best practice formatting of Python code files.
@@ -54,17 +54,17 @@ repos:
       - id: blacken-docs
         description: Run black on python code blocks in documentation files.
         files: ^(index|docs/.*|docs/_includes/.*)\.rst$
-        additional_dependencies: [black==24.10.0]
+        additional_dependencies: [black==25.1.0]
 
-#  - repo: https://github.com/saltstack/mirrors-nox
-#    rev: v2022.11.21
-#    hooks:
-#      - id: nox
-#        alias: Generate Sphinx docs
-#        description: Generate Sphinx docs, ensure they build
-#        pass_filenames: false
-#        args:
-#          - -e
-#          - 'docs-html(download_versions=True, clean=True)'
-#          - --
-#          - -vv
+  - repo: https://github.com/saltstack/mirrors-nox
+    rev: v2022.11.21
+    hooks:
+      - id: nox
+        alias: Generate Sphinx docs
+        description: Generate Sphinx docs, ensure they build
+        pass_filenames: false
+        args:
+          - -e
+          - 'docs-html(gen_sitevars=True, clean=True)'
+          - --
+          - -vv

.github/workflows/build-sphinx-docs.yml

@@ -177,5 +177,8 @@ def docs(session) -> None:
     args = ["--watch", ".", "--open-browser", "docs", str(build_dir)]
     if build_dir.exists():
         shutil.rmtree(build_dir)
+        # Generate sitevars
+        version_updater_script = Path("tools", "version-updater.py")
+        session.run("python", str(version_updater_script), external=True)
 
     session.run("sphinx-autobuild", *args)