chore: add devcontainer configuration (#288)

Author: mschoettle

.devcontainer/devcontainer.json

@@ -0,0 +1,42 @@
+// Format: https://containers.dev/implementors/json_reference/
+{
+  "name": "Python",
+  // Supported image versions: https://github.com/devcontainers/images/issues/90
+  // README: https://github.com/devcontainers/images/tree/main/src/python
+  "image": "mcr.microsoft.com/devcontainers/python:3.13-bookworm",
+  // https://containers.dev/features
+  "features": {
+    "ghcr.io/jsburckhardt/devcontainer-features/uv:1": {
+      "version": "0.6.13"
+    }
+  },
+  "postCreateCommand": "uv sync && git config push.autosetupremote true && uv run pre-commit install-hooks && uv run pre-commit install",
+  // Tool-specific properties: https://containers.dev/supporting
+  "customizations": {
+    "vscode": {
+      // see also .vscode/extensions.json
+      "extensions": [
+        "EditorConfig.EditorConfig",
+        "DavidAnson.vscode-markdownlint",
+        "redhat.vscode-yaml",
+        "streetsidesoftware.code-spell-checker",
+        "yzhang.markdown-all-in-one"
+      ],
+      // keep this in sync with .vscode/settings.json
+      "settings": {
+        // see: https://squidfunk.github.io/mkdocs-material/creating-your-site/?h=vscode#minimal-configuration-visual-studio-code
+        "yaml.schemas": {
+          "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+        },
+        "yaml.customTags": [
+          "!ENV scalar",
+          "!ENV sequence",
+          "!relative scalar",
+          "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
+          "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
+          "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+        ]
+      }
+    }
+  }
+}

.pre-commit-config.yaml

@@ -12,7 +12,14 @@ repos:
       - id: check-executables-have-shebangs
       - id: check-json
         # file contains comments
-        exclude: ^\.vscode/settings.json$
+        exclude: |
+          (?x)(
+            ^(
+              \.vscode/settings\.json
+              |\.vscode/extensions\.json
+              |\.devcontainer/devcontainer.json
+            )
+          )
       - id: check-merge-conflict
       - id: check-toml
       - id: check-xml
@@ -77,6 +84,12 @@ repos:
       - id: check-renovate
         args: ["--verbose"]
         additional_dependencies: ['json5']
+      # requires: https://github.com/python-jsonschema/check-jsonschema/issues/341
+      # - id: check-jsonschema
+      #   name: "Validate devcontainer"
+      #   files: ^\.devcontainer/.*\.json$
+      #   args: ["--schemafile", "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json"]
+      # waiting for custom YAML tags support: https://github.com/python-jsonschema/check-jsonschema/issues/489
       # - id: check-jsonschema
       #   name: "Validate MkDocs file"
       #   files: ^mkdocs\.ya?ml$

.vscode/extensions.json

@@ -1,8 +1,10 @@
 {
+  // keep in sync with extensions in .devcontainer/devcontainer.json
   "recommendations": [
     "editorconfig.editorconfig",
     "redhat.vscode-yaml",
     "davidanson.vscode-markdownlint",
-    "streetsidesoftware.code-spell-checker"
+    "streetsidesoftware.code-spell-checker",
+    "yzhang.markdown-all-in-one"
   ]
 }

.vscode/settings.json

@@ -1,4 +1,6 @@
+// keep in sync with settings in .devcontainer/devcontainer.json
 {
+  // see: https://squidfunk.github.io/mkdocs-material/creating-your-site/?h=vscode#minimal-configuration-visual-studio-code
   "yaml.schemas": {
     "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
   },

README.md

@@ -29,6 +29,10 @@ The documentation is split into several parts:
 
 ### Getting started
 
+> [!NOTE]
+> If you use [GitHub Codespaces](https://github.com/features/codespaces) or use a *Dev Container* extension, you do not need to do any of the below steps.
+> They are run automatically on startup.
+
 All you need is [`uv`](https://docs.astral.sh/uv) to set up your environment.
 
 ```shell

REUSE.toml

@@ -20,6 +20,7 @@ SPDX-License-Identifier = "CC-BY-SA-4.0"
 
 [[annotations]]
 path = [
+    ".devcontainer/devcontainer.json",
     ".vscode/extensions.json",
     ".vscode/settings.json",
 ]