Use MkDocs to publish a documentation website

.github/workflows/documentation.yml

@@ -0,0 +1,27 @@
+name: Documentation
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -1,2 +1,3 @@
 composer.lock
 vendor
+.cache

Makefile

@@ -0,0 +1,6 @@
+# This command is intended to be run on your computer
+serve-doc:
+	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+
+build-doc:
+	docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build

docs/assets/stylesheets/extra.css

@@ -0,0 +1,113 @@
+@font-face {
+  font-family: "Monaspace Neon";
+  font-weight: normal;
+  font-style: normal;
+  src: url("../fonts/MonaspaceNeon-Regular.woff");
+}
+
+:root {
+  --md-code-font: "Monaspace Neon";
+}
+
+:root {
+  --light-md-code-hl-number-color: #f76d47;
+  --light-md-code-hl-function-color: #6384b9;
+  --light-md-code-hl-operator-color: #39adb5;
+  --light-md-code-hl-constant-color: #7c4dff;
+  --light-md-code-hl-string-color: #9fc06f;
+  --light-md-code-hl-punctuation-color: #39adb5;
+  --light-md-code-hl-keyword-color: #7c4dff;
+  --light-md-code-hl-variable-color: #80cbc4;
+  --light-md-code-hl-comment-color: #ccd7da;
+  --light-md-code-bg-color: #fafafa;
+  --light-md-code-fg-color: #ffb62c;
+  --light-md-code-hl-variable-color: #6384b9;
+  --dark-md-code-hl-number-color: #f78c6c;
+  --dark-md-code-hl-function-color: #82aaff;
+  --dark-md-code-hl-operator-color: #89ddff;
+  --dark-md-code-hl-constant-color: #c792ea;
+  --dark-md-code-hl-string-color: #c3e88d;
+  --dark-md-code-hl-punctuation-color: #89ddff;
+  --dark-md-code-hl-keyword-color: #c792ea;
+  --dark-md-code-hl-variable-color: #e8f9f9;
+  --dark-md-code-hl-comment-color: #546e7a;
+  --dark-md-code-bg-color: #263238;
+  --dark-md-code-fg-color: #ffcb6b;
+  --dark-md-code-hl-variable-color: #82aaff;
+}
+
+@media (prefers-color-scheme: light) {
+  .language-php > * {
+    --md-code-hl-number-color: var(--light-md-code-hl-number-color);
+    --md-code-hl-function-color: var(--light-md-code-hl-function-color);
+    --md-code-hl-operator-color: var(--light-md-code-hl-operator-color);
+    --md-code-hl-constant-color: var(--light-md-code-hl-constant-color);
+    --md-code-hl-string-color: var(--light-md-code-hl-string-color);
+    --md-code-hl-punctuation-color: var(--light-md-code-hl-punctuation-color);
+    --md-code-hl-keyword-color: var(--light-md-code-hl-keyword-color);
+    --md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
+    --md-code-hl-comment-color: var(--light-md-code-hl-comment-color);
+    --md-code-bg-color: var(--light-md-code-bg-color);
+    --md-code-fg-color: var(--light-md-code-fg-color);
+  }
+
+  .language-php .na {
+    --md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
+  }
+}
+
+[data-md-color-media="(prefers-color-scheme: light)"] .language-php > * {
+  --md-code-hl-number-color: var(--light-md-code-hl-number-color);
+  --md-code-hl-function-color: var(--light-md-code-hl-function-color);
+  --md-code-hl-operator-color: var(--light-md-code-hl-operator-color);
+  --md-code-hl-constant-color: var(--light-md-code-hl-constant-color);
+  --md-code-hl-string-color: var(--light-md-code-hl-string-color);
+  --md-code-hl-punctuation-color: var(--light-md-code-hl-punctuation-color);
+  --md-code-hl-keyword-color: var(--light-md-code-hl-keyword-color);
+  --md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
+  --md-code-hl-comment-color: var(--light-md-code-hl-comment-color);
+  --md-code-bg-color: var(--light-md-code-bg-color);
+  --md-code-fg-color: var(--light-md-code-fg-color);
+}
+
+[data-md-color-media="(prefers-color-scheme: light)"] .language-php .na {
+  --md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
+}
+
+@media (prefers-color-scheme: dark) {
+  .language-php > * {
+    --md-code-hl-number-color: var(--dark-md-code-hl-number-color);
+    --md-code-hl-function-color: var(--dark-md-code-hl-function-color);
+    --md-code-hl-operator-color: var(--dark-md-code-hl-operator-color);
+    --md-code-hl-constant-color: var(--dark-md-code-hl-constant-color);
+    --md-code-hl-string-color: var(--dark-md-code-hl-string-color);
+    --md-code-hl-punctuation-color: var(--dark-md-code-hl-punctuation-color);
+    --md-code-hl-keyword-color: var(--dark-md-code-hl-keyword-color);
+    --md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
+    --md-code-hl-comment-color: var(--dark-md-code-hl-comment-color);
+    --md-code-bg-color: var(--dark-md-code-bg-color);
+    --md-code-fg-color: var(--dark-md-code-fg-color);
+  }
+
+  .language-php .na {
+    --md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
+  }
+}
+
+[data-md-color-media="(prefers-color-scheme: dark)"] .language-php > * {
+  --md-code-hl-number-color: var(--dark-md-code-hl-number-color);
+  --md-code-hl-function-color: var(--dark-md-code-hl-function-color);
+  --md-code-hl-operator-color: var(--dark-md-code-hl-operator-color);
+  --md-code-hl-constant-color: var(--dark-md-code-hl-constant-color);
+  --md-code-hl-string-color: var(--dark-md-code-hl-string-color);
+  --md-code-hl-punctuation-color: var(--dark-md-code-hl-punctuation-color);
+  --md-code-hl-keyword-color: var(--dark-md-code-hl-keyword-color);
+  --md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
+  --md-code-hl-comment-color: var(--dark-md-code-hl-comment-color);
+  --md-code-bg-color: var(--dark-md-code-bg-color);
+  --md-code-fg-color: var(--dark-md-code-fg-color);
+}
+
+[data-md-color-media="(prefers-color-scheme: dark)"] .language-php .na {
+  --md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
+}

docs/cli.md

@@ -2,7 +2,7 @@
 
 The first of any CLI app is to create an `entrypoint.php` that you'll call with the `php` command.
 
-```php
+```php title="entrypoint.php"
 <?php
 declare(strict_types = 1);
 
@@ -68,8 +68,12 @@ new class extends Cli {
                         ->with(Publish::one($message)->to('some-exchange'))
                         ->run($console)
                         ->match(
-                            static fn($console) => $console->output(Str::of("Message published\n")),
-                            static fn() => $console->error(Str::of("Something went wrong\n")),
+                            static fn($console) => $console->output(
+                                Str::of("Message published\n"),
+                            ),
+                            static fn() => $console->error(
+                                Str::of("Something went wrong\n"),
+                            ),
                         );
                 }
 
@@ -91,8 +95,12 @@ new class extends Cli {
                         ->with(Get::of('some-queue'))
                         ->run($console)
                         ->match(
-                            static fn($console) => $console->output(Str::of("One message pulled from queue\n")),
-                            static fn() => $console->error(Str::of("Something went wrong\n")),
+                            static fn($console) => $console->output(
+                                Str::of("One message pulled from queue\n"),
+                            ),
+                            static fn() => $console->error(
+                                Str::of("Something went wrong\n"),
+                            ),
                         );
                 }
 

docs/environment.md

@@ -1,6 +1,6 @@
 # Add variables to the environment
 
-The framework exposes an [`Environment`](../src/Environment.php) object with values coming from `\getenv()`. If you want to add variables and make them available to the rest of your application you can do it like this:
+The framework exposes an [`Environment`](https://github.com/Innmind/framework/blob/develop/src/Environment.php) object with values coming from `\getenv()`. If you want to add variables and make them available to the rest of your application you can do it like this:
 
 ```php
 use Innmind\Framework\{
@@ -13,10 +13,12 @@ use Innmind\Framework\{
 new class extends Http|Cli {
     protected function configure(Application $app): Application
     {
-        return $app->mapEnvironment(static fn(Environment $env) => $env->with(
-            'MY_VARIABLE_NAME',
-            "and it's value",
-        ));
+        return $app->mapEnvironment(
+            static fn(Environment $env) => $env->with(
+                'MY_VARIABLE_NAME',
+                "and it's value",
+            ),
+        );
     }
 };
 ```

docs/experimental/async-server.md

@@ -2,8 +2,8 @@
 
 The framework comes with an HTTP server entirely built in PHP allowing you to serve your app without extra dependencies in ther earlist stages of your project.
 
-> [!NOTE]
-> This feature is optional, to use it you must before run `composer require innmind/async-http-server`.
+!!! note ""
+    This feature is optional, to use it you must before run `composer require innmind/async-http-server`.
 
 To use it is similar to the standard [http](../http.md) handler, the first difference is the namespace of the main entrypoint:
 
@@ -30,8 +30,8 @@ Note the namespace is `Main\Async\Http` instead of `Main\Http`. The other differ
 
 All the configuration of the `Application` object is identical to the other contexts.
 
-> [!NOTE]
->The server currently does have limitations, streamed requests (via `Transfer-Encoding`) are not supported and multipart requests are not parsed.
+!!! note ""
+    The server currently does have limitations, streamed requests (via `Transfer-Encoding`) are not supported and multipart requests are not parsed.
 
-> [!WARNING]
-> This server was built to showcase in a conference talk the ability to switch between synchronous code and asynchronous code without changing the app code. Do **NOT** use this server in production.
+!!! warning ""
+    This server was built to showcase in a conference talk the ability to switch between synchronous code and asynchronous code without changing the app code. Do **NOT** use this server in production.

docs/http-and-cli.md

@@ -23,10 +23,12 @@ final class Kernel implements Middleware
         return $app
             ->service(
                 'images',
-                static fn($_, OperatingSystem $os) => $os->filesystem()->mount(Path::of('somewhere/on/the/filesystem/')),
+                static fn($_, OperatingSystem $os) => $os
+                    ->filesystem()
+                    ->mount(Path::of('somewhere/on/the/filesystem/')),
             )
             ->service('amqp', /* see services topic */)
-            ->service('upload', static fn(Container $container) => new UploadHandler( // imaginary class
+            ->service('upload', static fn(Container $container) => new UploadHandler( //(1)
                 $container('images'),
                 $container('amqp'),
             ))
@@ -35,14 +37,17 @@ final class Kernel implements Middleware
                     Route::literal('POST /upload')->handle(Service::of($container, 'upload')),
                 ),
             )
-            ->command(static fn(Container $container) => new ThumbnailWorker( // imaginary class
+            ->command(static fn(Container $container) => new ThumbnailWorker( //(2)
                 $container('images'),
                 $container('amqp'),
             ));
     }
 }
 ```
 
+1. imaginary class
+2. imaginary class
+
 Then you can use this middleware like this:
 
 ```php