Merge branch 'develop'

* develop:
  styling
  add navigation
  rename readme to index
  setup mkdocs

.github/workflows/documentation.yml

@@ -0,0 +1,27 @@
+name: Documentation
+on:
+  push:
+    branches: [master]
+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

@@ -2,3 +2,4 @@ composer.lock
 vendor
 .phpunit.result.cache
 .phpunit.cache
+.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

documentation/advanced/logging.md

@@ -2,8 +2,8 @@
 
 If you want to trace everything that is done on your operating system you can use the logger decorator that will automatically write to your log file (almost) all operations.
 
-> [!NOTE]
-> data and actions done on a socket are not logged as well as processes output to prevent logging too much data (at least for now).
+!!! note ""
+    Data and actions done on a socket are not logged as well as processes output to prevent logging too much data (at least for now).
 
 ```php
 use Innmind\OperatingSystem\OperatingSystem\Logger;

documentation/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);
+}

documentation/readme.md → documentation/index.md

@@ -1,3 +1,9 @@
+---
+hide:
+    - navigation
+    - toc
+---
+
 # Getting started
 
 This library is here to help abstract all the operations that involve the operating system the PHP code run on.
@@ -8,8 +14,8 @@ The other advantage to use higher level abstractions is to enable end user to bu
 
 For concrete examples have a look at the use cases available in the sidebar.
 
-> [!NOTE]
-> this library is a small overlay on top of a set of individual libraries that contain the concrete abstractions. So you can start using only a subset of abstractions in your code as a starting point.
+!!! note ""
+    This library is a small overlay on top of a set of individual libraries that contain the concrete abstractions. So you can start using only a subset of abstractions in your code as a starting point.
 
 ## Installation
 
@@ -27,21 +33,5 @@ $os = Factory::build();
 
 There's nothing more to add to start using this abstraction. Head toward the use cases to understand all the things you can do with it.
 
-> [!WARNING]
-> This library doesn't work on windows environments.
-
-## Use cases
-
-- [Manipulating time](use_cases/time.md)
-- [Filesystem](use_cases/filesystem.md)
-- [HTTP Client](use_cases/http.md)
-- [Processes](use_cases/processes.md)
-- [Inter Process Communication](use_cases/ipc.md)
-- [Socket communication](use_cases/socket.md)
-- [Handling process signals](use_cases/signals.md)
-- [SQL connection](use_cases/sql.md)
-
-## Advanced usage
-
-- [Logging all operations](advanced/logging.md)
-- [Extensions](advanced/extensions.md)
+!!! warning ""
+    This library doesn't work on windows environments.

documentation/use_cases/filesystem.md

@@ -37,7 +37,11 @@ use Innmind\Filesystem\{
 use Innmind\Url\Path;
 use Innmind\Immutable\Predicate\Instance;
 
-$addUserPicture = function(Adapter $filesystem, string $userId, File $picture): void {
+$addUserPicture = function(
+    Adapter $filesystem,
+    string $userId,
+    File $picture,
+): void {
     $filesystem
         ->get(Name::of($userId))
         ->keep(Instance::of(Directory::class))
@@ -73,7 +77,9 @@ Example of checking if a `maintenance.lock` exist to prevent your webapp from ru
 ```php
 use Innmind\Url\Path;
 
-if ($os->filesystem()->contains(Path::of('/path/to/project/maintenance.lock'))) {
+$path = Path::of('/path/to/project/maintenance.lock');
+
+if ($os->filesystem()->contains($path)) {
     throw new \RuntimeException('Application still in maintenance');
 }
 
@@ -85,7 +91,9 @@ Or you could check the existence of a directory that is required for another sub
 ```php
 use Innmind\Url\Path;
 
-if (!$os->filesystem()->contains(Path::of('/path/to/some/required/folder/'))) {
+$path = Path::of('/path/to/some/required/folder/');
+
+if (!$os->filesystem()->contains($path)) {
     $os->control()->processes()->execute($mkdirCommand);
 }
 
@@ -116,20 +124,23 @@ use Innmind\FileWatch\Continuation;
 
 $runTests = $os->filesystem()->watch(Path::of('/path/to/project/src/'));
 
-$count = $runTests(0, function(int $count, Continuation $continuation) use ($os): Continuation {
-    if ($count === 42) {
-        return $continuation->stop($count);
-    }
+$count = $runTests(
+    0,
+    function(int $count, Continuation $continuation) use ($os): Continuation {
+        if ($count === 42) {
+            return $continuation->stop($count);
+        }
 
-    $os->control()->processes()->execute($phpunitCommand);
+        $os->control()->processes()->execute($phpunitCommand);
 
-    return $continuation->continue(++$count);
-});
+        return $continuation->continue(++$count);
+    },
+);
 ```
 
 Here it will run phpunit tests every time the `src/` folder changes. Concrete examples of this pattern can be found in [`innmind/lab-station`](https://github.com/Innmind/LabStation/blob/develop/src/Agent/WatchSources.php#L38) to run a suite of tools when sources change.
 
 This operation is a bit like an `array_reduce` as you can keep a state record between each calls of the callable via the first argument (here `0`, but it can be anything) and the argument of your callable will be the previous value returned by `$continuation->continue()`.
 
-> [!WARNING]
-> since there is no builtin way to watch for changes in a directory it checks the directory every second, so use it with care. Watching an individual file is a bit safer as it uses the `tail` command so there is no `sleep()` used.
+!!! warning ""
+    Since there is no builtin way to watch for changes in a directory it checks the directory every second, so use it with care. Watching an individual file is a bit safer as it uses the `tail` command so there is no `sleep()` used.

documentation/use_cases/http.md

@@ -28,8 +28,8 @@ $response instanceof Response; // true
 
 All elements of a request/response call is built using objects to enforce correctness of the formatted messages.
 
-> [!NOTE]
-> since request and responses messages can be viewed either from a client or a server the model is abstracted in the standalone [`innmind/http` library](https://github.com/innmind/http).
+!!! note ""
+    Since request and responses messages can be viewed either from a client or a server the model is abstracted in the standalone [`innmind/http` library](https://github.com/innmind/http).
 
 ## Resiliency in a distributed system
 
@@ -63,5 +63,5 @@ $response = $http($request);
 $response = $http($request);
 ```
 
-> [!NOTE]
-> the circuit breaker works on host per host basis meaning if `server1.com` fails then calls to `server2.com` will still be sent.
+!!! note ""
+    The circuit breaker works on host per host basis meaning if `server1.com` fails then calls to `server2.com` will still be sent.

documentation/use_cases/ipc.md

@@ -4,8 +4,8 @@ To communicate between processes on a same system there is 2 approaches: sharing
 
 The later is the safest of the two (but not exempt of problems) and you will find here the building blocks to communicate via a socket.
 
-> [!TIP]
-> the adage `share state through messages and not messages through state` is a pillar of the [actor model](https://en.wikipedia.org/wiki/Actor_model) and [initially of object oriented programming](https://www.youtube.com/watch?v=7erJ1DV_Tlo).
+!!! tip ""
+    The adage `share state through messages and not messages through state` is a pillar of the [actor model](https://en.wikipedia.org/wiki/Actor_model) and [initially of object oriented programming](https://www.youtube.com/watch?v=7erJ1DV_Tlo).
 
 ```php
 # process acting as a server
@@ -61,5 +61,5 @@ echo $client
 
 In the case the server is started first then the client would print `Hello`.
 
-> [!WARNING]
-> this is a very rough implementation of communication between processes. **DO NOT** use this simple implementation in your code, instead use a higher level API such as [`innmind/ipc`](https://github.com/innmind/ipc).
+!!! warning ""
+    This is a very rough implementation of communication between processes. **DO NOT** use this simple implementation in your code, instead use a higher level API such as [`innmind/ipc`](https://github.com/innmind/ipc).

documentation/use_cases/processes.md

@@ -90,7 +90,11 @@ $backupRunning = $os
     ->status()
     ->processes()
     ->all()
-    ->any(fn($process): bool => $process->command()->matches(RegExp::of('~my-backup-tool~')));
+    ->any(
+        fn($process): bool => $process
+            ->command()
+            ->matches(RegExp::of('~my-backup-tool~')),
+    );
 
 if (!$backupRunning) {
     $os->control()->processes()->execute(

documentation/use_cases/signals.md

@@ -19,15 +19,21 @@ use Innmind\Immutable\{
     Str,
 };
 
-$client = $os->remote()->socket(Transport::tcp(), Ur::of('tcp://127.0.0.1:8080')->authority())->match(
-    static fn($client) => $client,
-    static fn() => throw new \RuntimeException('Unable to connect to the server'),
-);
+$client = $os
+    ->remote()
+    ->socket(Transport::tcp(), Url::of('tcp://127.0.0.1:8080')->authority())
+    ->match(
+        static fn($client) => $client,
+        static fn() => throw new \RuntimeException('Unable to connect to the server'),
+    );
 $watch = $os->sockets()->watch(new ElapsedPeriod(1000))->forRead($client);
 $signaled = true;
-$os->process()->signals()->listen(Signal::terminate, function() use (&$signaled) {
-    $signaled = false;
-});
+$os
+    ->process()
+    ->signals()
+    ->listen(Signal::terminate, function() use (&$signaled) {
+        $signaled = false;
+    });
 
 $receivedData = $client
     ->timeoutAfter(ElapsedPeriod::of(1_000))
@@ -52,8 +58,8 @@ $client->unwrap()->close();
 
 When the process receive the `SIGTERM` signal it will be paused then the anonymous function will be called and the process will then be resumed.
 
-> [!NOTE]
-> signal handling is already performed when using [`innmind/ipc`](https://github.com/innmind/ipc) or [`innmind/amqp`](https://github.com/innmind/amqp) so you don't have to think about it.
+!!! note ""
+    Signal handling is already performed when using [`innmind/ipc`](https://github.com/innmind/ipc) or [`innmind/amqp`](https://github.com/innmind/amqp) so you don't have to think about it.
 
 ## Prevent process from being stopped