docs(📝): add mkdocs for automatic self-documentation

.devcontainer/devcontainer.json

@@ -17,7 +17,9 @@
         "ms-toolsai.jupyter",
         "pkief.material-icon-theme",
         "redhat.vscode-yaml",
-        "tamasfe.even-better-toml"
+        "tamasfe.even-better-toml",
+        "ms-vscode.vscode-websearchforcopilot",
+        "ms-vscode.vscode-commander"
       ],
       "settings": {
         "editor.linkedEditing": true,
@@ -57,6 +59,19 @@
         "python.testing.cwd": "${containerWorkspaceFolder}/tests",
         "python.testing.pytestPath": "${containerWorkspaceFolder}/.venv/bin/pytest",
         "python.testing.autoTestDiscoverOnSaveEnabled": true,
+        // MkDocs schema for the YAML extension
+        "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",
+          "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
+        ],
         // Settings per file type
         "[toml]": {
           "editor.defaultFormatter": "tamasfe.even-better-toml",
@@ -86,5 +101,8 @@
     "ghcr.io/thecodecrate/devcontainer-features/uv:1": {}
   },
   "remoteUser": "vscode",
-  "postCreateCommand": "zsh -i .devcontainer/scripts/post-create.sh"
+  "postCreateCommand": "zsh -i .devcontainer/scripts/post-create.sh",
+  "containerEnv": {
+    "PYTHONPATH": "${containerWorkspaceFolder}/src"
+  }
 }

.github/workflows/format-ruff.yaml

@@ -7,6 +7,8 @@ on:
     branches:
       - main
 
+permissions: {}
+
 jobs:
   format-ruff:
     name: Ruff Check

.github/workflows/lint-ruff.yaml

@@ -7,6 +7,8 @@ on:
     branches:
       - main
 
+permissions: {}
+
 jobs:
   lint-ruff:
     name: Ruff Check

.github/workflows/release.yaml

@@ -6,6 +6,8 @@ on:
     tags:
       - '*'
 
+permissions: {}
+
 jobs:
   deploy:
     runs-on: ubuntu-latest

.github/workflows/security-zizmor.yaml

@@ -7,6 +7,8 @@ on:
     branches:
       - main
 
+permissions: {}
+
 jobs:
   zizmor:
     name: Zizmor CI files check

.github/workflows/test.yaml

@@ -7,6 +7,8 @@ on:
     branches:
       - main
 
+permissions: {}
+
 jobs:
   test:
     name: Python ${{ matrix.python-version }} - ${{ matrix.os }}

docs/api/core.md

@@ -0,0 +1,15 @@
+# API Reference
+
+::: thecodecrate_pipeline.core
+    options:
+        show_if_no_docstring: true
+        preload_modules:
+            - "_api"
+            - "thecodecrate_pipeline"
+        members:
+            - T_in
+            - T_out
+            - Pipeline
+            - PipelineFactory
+            - Stage
+            - Processor

docs/api/processors.md

@@ -0,0 +1,13 @@
+# API Reference
+
+::: thecodecrate_pipeline.processors
+    options:
+        show_if_no_docstring: true
+        preload_modules:
+            - "_api"
+            - "thecodecrate_pipeline"
+        members:
+            - ChainedProcessor
+            - InterruptibleProcessor
+            - ChainedProcessorInterface
+            - InterruptibleProcessorInterface

docs/assets/css/extra.css

@@ -0,0 +1,48 @@
+/* Symbols in Navigation and ToC. */
+:root, :host,
+[data-md-color-scheme="default"] {
+  --doc-symbol-parameter-fg-color: #df50af;
+  --doc-symbol-attribute-fg-color: #953800;
+  --doc-symbol-function-fg-color: #8250df;
+  --doc-symbol-method-fg-color: #8250df;
+  --doc-symbol-class-fg-color: #0550ae;
+  --doc-symbol-module-fg-color: #5cad0f;
+
+  --doc-symbol-parameter-bg-color: #df50af1a;
+  --doc-symbol-attribute-bg-color: #9538001a;
+  --doc-symbol-function-bg-color: #8250df1a;
+  --doc-symbol-method-bg-color: #8250df1a;
+  --doc-symbol-class-bg-color: #0550ae1a;
+  --doc-symbol-module-bg-color: #5cad0f1a;
+}
+
+[data-md-color-scheme="dracula"] {
+  --doc-symbol-parameter-fg-color: #ffa8cc;
+  --doc-symbol-attribute-fg-color: #ffa657;
+  --doc-symbol-function-fg-color: #d2a8ff;
+  --doc-symbol-method-fg-color: #d2a8ff;
+  --doc-symbol-class-fg-color: #79c0ff;
+  --doc-symbol-module-fg-color: #baff79;
+
+  --doc-symbol-parameter-bg-color: #ffa8cc1a;
+  --doc-symbol-attribute-bg-color: #ffa6571a;
+  --doc-symbol-function-bg-color: #d2a8ff1a;
+  --doc-symbol-method-bg-color: #d2a8ff1a;
+  --doc-symbol-class-bg-color: #79c0ff1a;
+  --doc-symbol-module-bg-color: #baff791a;
+}
+
+code.doc-symbol-heading.doc-symbol-module {
+    color: var(--doc-symbol-module-fg-color) !important;
+    background-color: var(--doc-symbol-module-bg-color) !important;
+}
+
+code.doc-symbol-heading.doc-symbol-class {
+    color: var(--doc-symbol-class-fg-color) !important;
+    background-color: var(--doc-symbol-class-bg-color) !important;
+}
+
+code.doc-symbol-heading.doc-symbol-method {
+    color: var(--doc-symbol-method-fg-color) !important;
+    background-color: var(--doc-symbol-method-bg-color) !important;
+}