Migrate the documentation from MkDocs to Zensical

.gitattributes

@@ -7,10 +7,8 @@
 /castor.php             export-ignore
 /castor.composer.json   export-ignore
 /castor.composer.lock   export-ignore
-/mkdocs.yaml            export-ignore
+/zensical.toml          export-ignore
 /phpstan.neon           export-ignore
 /phpunit.xml            export-ignore
-/pyproject.toml         export-ignore
-/poetry.lock            export-ignore
 /bootstrap.php          export-ignore
 /.github/           export-ignore

.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+    - package-ecosystem: 'github-actions'
+      directory: '/'
+      schedule:
+          interval: 'monthly'
+      groups:
+          github-actions:
+              patterns:
+                  - '*'
+          github-actions-security:
+              applies-to: security-updates
+              patterns:
+                  - '*'
+      cooldown:
+          default-days: 7

.github/workflows/ci.yml

@@ -8,30 +8,39 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: checkout
-        uses: actions/checkout@master
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: setup
-        uses: castor-php/setup-castor@v0.1.0
+        uses: castor-php/setup-castor@2a495b8c91f00be6768ad8a040ba8634c797d386 # v1.1.0
       - name: 'php-cs-fixer check'
         run: 'castor qa:cs:check'
+  doc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: setup
+        uses: castor-php/setup-castor@2a495b8c91f00be6768ad8a040ba8634c797d386 # v1.1.0
+      - name: 'documentation build'
+        run: 'castor doc:build'
   phpstan:
     runs-on: ubuntu-latest
     steps:
       - name: checkout
-        uses: actions/checkout@master
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: cache-composer
-        uses: actions/cache@v4
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ~/.composer/cache/
           key: composer-${{ github.sha }}
       - name: setup
-        uses: shivammathur/setup-php@2.32.0
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: 8.4
           coverage: none
       - name: composer install
         run: composer update --prefer-stable
       - name: setup
-        uses: castor-php/setup-castor@v0.1.0
+        uses: castor-php/setup-castor@2a495b8c91f00be6768ad8a040ba8634c797d386 # v1.1.0
       - name: 'phpstan check'
         run: 'castor qa:phpstan'
   tests:
@@ -45,14 +54,14 @@ jobs:
           - 8.5
     steps:
       - name: checkout
-        uses: actions/checkout@master
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: cache-composer
-        uses: actions/cache@v4
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ~/.composer/cache/
           key: composer-${{ github.sha }}
       - name: setup
-        uses: shivammathur/setup-php@2.32.0
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: '${{ matrix.php-versions }}'
           coverage: none
@@ -66,14 +75,14 @@ jobs:
     name: tests-lowest
     steps:
       - name: checkout
-        uses: actions/checkout@master
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: cache-composer
-        uses: actions/cache@v4
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ~/.composer/cache/
           key: composer-${{ github.sha }}
       - name: setup
-        uses: shivammathur/setup-php@2.32.0
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0
         with:
           php-version: 8.4
           coverage: none

.github/workflows/documentation.yml

@@ -23,33 +23,22 @@ concurrency:
 
 jobs:
   build:
-    name: Build documentation website with MkDocs
+    name: Build documentation website with Zensical
     runs-on: ubuntu-latest
     steps:
-      - name: Setup Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.11"
-
-      - name: Install poetry
-        run: pip install -U poetry
-
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           fetch-depth: 0
           fetch-tags: true
 
-      - name: Install dependencies
-        run: poetry install
-
       - name: setup
-        uses: castor-php/setup-castor@v0.1.0
+        uses: castor-php/setup-castor@2a495b8c91f00be6768ad8a040ba8634c797d386 # v1.1.0
 
       - name: Setup Pages
         id: pages
-        uses: actions/configure-pages@v4
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
 
       - name: Build documentation
         run: castor doc:build-github-pages
@@ -58,7 +47,7 @@ jobs:
         run: ls ./.build
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: ./.build
 
@@ -72,4 +61,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

castor.php

@@ -82,24 +82,49 @@ function debug_mapper(string $source, string $target, string $load = ''): void
     $command->run($input, \Castor\output());
 }
 
-#[AsTask('install', namespace: 'doc', description: 'Install tool for documentation (need poetry)')]
-function doc_install(): void
+const DOC_DOCKER_IMAGE = 'automapper-doc';
+
+#[AsTask('docker-build', namespace: 'doc', description: 'Build the documentation docker image')]
+function doc_docker_build(): void
 {
-    run('poetry install');
+    run(['docker', 'build', '-t', DOC_DOCKER_IMAGE, __DIR__ . '/docs']);
 }
 
-#[AsTask('server', namespace: 'doc', description: 'Serve documentation')]
+#[AsTask('build', namespace: 'doc', description: 'Build documentation')]
+function doc_build(): void
+{
+    doc_run(['zensical', 'build', '--strict']);
+}
+
+#[AsTask('server', namespace: 'doc', description: 'Serve documentation and watch for changes')]
 function doc_serve(): void
 {
-    run('poetry run mkdocs serve -a localhost:8000');
+    doc_run(['zensical', 'serve', '--dev-addr', 'localhost:8000']);
+}
+
+function doc_run(array $command): void
+{
+    $image = run(['docker', 'image', 'inspect', DOC_DOCKER_IMAGE], context: context()->withAllowFailure()->withQuiet());
+    if (!$image->isSuccessful()) {
+        doc_docker_build();
+    }
+
+    run([
+        'docker', 'run', '--init', '--rm', '--network=host',
+        '--user', getmyuid() . ':' . getmygid(),
+        '--env', 'HOME=/tmp',
+        '--volume', __DIR__ . ':/app',
+        DOC_DOCKER_IMAGE,
+        ...$command,
+    ]);
 }
 
 #[AsTask(description: 'Fetch external assets and customize theme', namespace: 'doc')]
 function build_assets(): void
 {
-    io()->title('Fetching external assets for MkDocs documentation');
+    io()->title('Fetching external assets for documentation');
 
-    http_download('https://raw.githubusercontent.com/jolicode/oss-theme/refs/heads/main/MkDocs/extra.css', __DIR__ . '/docs/assets/stylesheets/jolicode.css');
+    http_download('https://raw.githubusercontent.com/jolicode/oss-theme/refs/heads/main/Zensical/extra.css', __DIR__ . '/docs/assets/stylesheets/jolicode.css');
     http_download('https://raw.githubusercontent.com/jolicode/oss-theme/refs/heads/main/snippet-joli-footer.html', __DIR__ . '/docs/overrides/jolicode-footer.html');
 
     $html = <<<'HTML'
@@ -116,7 +141,7 @@ function build_assets(): void
     file_put_contents(__DIR__ . '/docs/overrides/jolicode-footer.html', $footer);
 }
 
-#[AsTask('build-github-pages', namespace: 'doc', description: 'Serve documentation')]
+#[AsTask('build-github-pages', namespace: 'doc', description: 'Build every version of the documentation for GitHub Pages')]
 function doc_build_github_pages(): void
 {
     // clean .build directory
@@ -135,7 +160,7 @@ function doc_build_github_pages(): void
     run('git config receive.denyCurrentBranch ignore', context: $context);
 
     // build documentation for main branch
-    run('poetry run mike deploy --push --remote gh-pages dev');
+    doc_run(['mike', 'deploy', '--push', '--remote', 'gh-pages', 'dev']);
 
     // get the list of tags
     $tags = run('git tag --list', context: context()->withQuiet())->getOutput();
@@ -174,9 +199,9 @@ function doc_build_github_pages(): void
         run('git checkout tags/' . $tag);
 
         if ($tag === $latestVersion) {
-            run('poetry run mike deploy --push --remote gh-pages ' . $tag . ' latest');
+            doc_run(['mike', 'deploy', '--push', '--remote', 'gh-pages', $tag, 'latest']);
         } else {
-            run('poetry run mike deploy --push --remote gh-pages --update-aliases ' . $tag);
+            doc_run(['mike', 'deploy', '--push', '--remote', 'gh-pages', '--update-aliases', $tag]);
         }
     }
 

docs/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3-slim
+
+WORKDIR /app/
+
+# git is needed by mike, to deploy the versions of the documentation
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# mike: Zensical-compatible fork, until Zensical ships native versioning
+RUN pip install \
+    zensical \
+    markdown-callouts \
+    git+https://github.com/squidfunk/mike.git
+
+CMD ["zensical", "serve"]

docs/assets/stylesheets/jolicode.css

@@ -1,6 +1,14 @@
 :root  > * {
     --md-primary-color: #f7d325;
     --md-typeset-a-color: #ea1340;
+
+    /* Zensical "modern" variant ignores palette primary/accent names, make them follow the link color (red in light, yellow in dark) */
+    --md-primary-fg-color: var(--md-typeset-a-color);
+    --md-primary-fg-color--light: var(--md-typeset-a-color);
+    --md-primary-fg-color--dark: var(--md-typeset-a-color);
+    --md-primary-bg-color: #fff;
+    --md-accent-fg-color: var(--md-typeset-a-color);
+    --md-accent-fg-color--transparent: color-mix(in srgb, var(--md-typeset-a-color) 10%, transparent);
 }
 
 [data-md-color-scheme=slate][data-md-color-primary=black] {
@@ -62,6 +70,10 @@
         text-decoration: underline;
     }
 
+    .md-button:not(.md-button--primary) {
+        color: var(--md-typeset-a-color);
+    }
+
     blockquote {
         color: var(--md-default-fg-color);
         border: 1px solid var(--md-default-fg-color--lightest);