Merge pull request #19 from Innmind/mkdocs

Use MkDocs to publish a documentation website

.github/workflows/documentation.yml

@@ -0,0 +1,27 @@
+name: ci
+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

@@ -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

README.md

@@ -6,7 +6,7 @@
 
 A set of classes to wrap PHP primitives to build immutable data.
 
-[Documentation](docs/README.md)
+[Documentation](https://innmind.github.io/Immutable/)
 
 ## Installation
 

docs/MONOIDS.md

@@ -1,10 +1,17 @@
+---
+hide:
+    - navigation
+    - toc
+---
+
 # Monoids
 
 Monoids describe a way to combine two values of a given type. A monoid contains an identity value that when combined with another value doesn't change its value. The combine operation has to be associative meaning `combine(a, combine(b, c))` is the same as `combine(combine(a, b), c)`.
 
 A simple monoid is an addition because adding `0` (the identity value) to any other integer won't change the value and `add(1, add(2, 3))` is the the same result as `add(add(1, 2), 3)` (both return 6).
 
 This library comes with a few monoids:
+
 - `Innmind\Immutable\Monoid\Concat` to append 2 instances of `Innmind\Immutable\Str` together
 - `Innmind\Immutable\Monoid\Append` to append 2 instances of `Innmind\Immutable\Sequence` together
 - `Innmind\Immutable\Monoid\MergeSet` to append 2 instances of `Innmind\Immutable\Set` together
@@ -38,3 +45,5 @@ return static function() {
     }
 };
 ```
+
+You can take a look at the [proofs](https://github.com/Innmind/Immutable/tree/master/proofs/monoid) for this package monoids to better understand how thiw works.

docs/PHILOSOPHY.md

@@ -1,6 +1,13 @@
+---
+hide:
+    - navigation
+    - toc
+---
+
 # Philosophy
 
 This project was born after working with other programming languages (like [Scala](https://scala-lang.org)) and discovering [functional programming](https://en.wikipedia.org/wiki/Functional_programming). This taught me 2 things:
+
 - higher order functions on data structures
 - immutability
 

docs/README.md

@@ -1,3 +1,9 @@
+---
+hide:
+    - navigation
+    - toc
+---
+
 # Getting Started
 
 This project brings a set of immutable data structure to bring a uniformity on how to handle data.
@@ -9,31 +15,3 @@ Before diving in the documentation you may want to read about the [philosophy](P
 ```sh
 composer require innmind/immutable
 ```
-
-## Structures
-
-This library provides the 10 following structures:
-
-- [`Sequence`](SEQUENCE.md)
-- [`Set`](SET.md)
-- [`Map`](MAP.md)
-- [`Str`](STR.md)
-- [`RegExp`](REGEXP.md)
-- [`Maybe`](MAYBE.md)
-- [`Either`](EITHER.md)
-- [`Validation`](VALIDATION.md)
-- [`State`](STATE.md)
-- [`Fold`](FOLD.md)
-
-See the documentation for each structure to understand how to use them.
-
-All structures are typed with [`vimeo/psalm`](https://psalm.dev), you must use it in order to verify that you use this library correctly.
-
-## Use cases
-
-- [How to read a file](LAZY_FILE.md)
-- [Parsing strings](PARSING.md)
-
-## Testing
-
-This package provides sets that can be used with [BlackBox](BLACKBOX.md).

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/EITHER.md → docs/structures/either.md

@@ -32,8 +32,8 @@ function accessResource(User $user): Either {
 }
 ```
 
-> **Note**
-> `ServerRequest`, `User`, `Resource` and `Error` are imaginary classes.
+!!! note ""
+    `ServerRequest`, `User`, `Resource` and `Error` are imaginary classes.
 
 ## `::left()`
 
@@ -43,8 +43,8 @@ This builds an `Either` instance with the given value in the left hand side.
 $either = Either::left($anyValue);
 ```
 
-> **Note**
-> usually this side is used for errors.
+!!! note ""
+    Usually this side is used for errors.
 
 ## `::right()`
 
@@ -54,8 +54,8 @@ This builds an `Either` instance with the given value in the right hand side.
 $either = Either::right($anyValue);
 ```
 
-> **Note**
-> usually this side is used for valid values.
+!!! note ""
+    Usually this side is used for valid values.
 
 ## `::defer()`
 
@@ -75,7 +75,8 @@ $either = Either::defer(static function() {
 
 Methods called (except `match`) on a deferred `Either` will not be called immediately but will be composed to be executed once you call `match`.
 
-> **Warning** this means that if you never call `match` on a deferred `Either` it will do nothing.
+!!! warning ""
+    This means that if you never call `match` on a deferred `Either` it will do nothing.
 
 ## `->map()`
 
@@ -85,7 +86,9 @@ This will apply the map transformation on the right value if there is one, other
 /** @var Either<Error, User> */
 $either = identify($serverRequest);
 /** @var Either<Error, Impersonated> */
-$impersonated = $either->map(fn(User $user): Impersonated => $user->impersonateAdmin());
+$impersonated = $either->map(
+    fn(User $user): Impersonated => $user->impersonateAdmin(),
+);
 ```
 
 ## `->flatMap()`
@@ -109,12 +112,14 @@ $response = identify($serverRequest)
     ->flatMap(fn(User $user): Either => accessResource($user))
     ->match(
         fn(Resource $resource) => new Response(200, $resource->toString()),
-        fn(Error $error) => new Response(400, $error->message()), // here the error can be from identify or from accessResource
+        fn(Error $error) => new Response(400, $error->message()), //(1)
     );
 ```
 
-> **Note**
-> `Response` is an imaginary class.
+1. Here the error can be from `identify` or from `accessResource`.
+
+!!! note ""
+    `Response` is an imaginary class.
 
 ## `->otherwise()`
 
@@ -148,11 +153,14 @@ identify($request)
         fn() => new Error('User is not allowed'),
     )
     ->match(
-        fn(User $user) => doSomething($user), // here we know the user is allowed
-        fn(Error $error) => print($error->message()), // can be "User not found" or "User is not allowed"
+        fn(User $user) => doSomething($user), //(1)
+        fn(Error $error) => print($error->message()), //(2)
     );
 ```
 
+1. Here we know the user is allowed.
+2. Can be "User not found" or "User is not allowed".
+
 ## `->leftMap()`
 
 This is similar to the `->map()` function but will be applied on the left value only.
@@ -165,7 +173,7 @@ $either = identify($request)
 
 ## `->maybe()`
 
-This returns a [`Maybe`](MAYBE.md) containing the right value, in case of a left value it returns a `Maybe` with nothing inside.
+This returns a [`Maybe`](maybe.md) containing the right value, in case of a left value it returns a `Maybe` with nothing inside.
 
 ```php
 Either::right('something')->maybe()->match(

docs/FOLD.md → docs/structures/fold.md

@@ -1,6 +1,6 @@
 # `Fold`
 
-The `Fold` monad is intented to work with _(infinte) stream of data_ by folding each element to a single value. This monad distinguishes between the type used to fold and the result type, this allows to inform the _stream_ that it's no longer necessary to extract elements as the folding is done.
+The `Fold` monad is intented to work with _(infinite) stream of data_ by folding each element to a single value. This monad distinguishes between the type used to fold and the result type, this allows to inform the _stream_ that it's no longer necessary to extract elements as the folding is done.
 
 An example is reading from a socket as it's an infinite stream of strings:
 

docs/structures/index.md

@@ -0,0 +1,18 @@
+# Structures
+
+This library provides the 10 following structures:
+
+- [`Sequence`](sequence.md)
+- [`Set`](set.md)
+- [`Map`](map.md)
+- [`Str`](str.md)
+- [`RegExp`](regexp.md)
+- [`Maybe`](maybe.md)
+- [`Either`](either.md)
+- [`Validation`](validation.md)
+- [`State`](state.md)
+- [`Fold`](fold.md)
+
+See the documentation for each structure to understand how to use them.
+
+All structures are typed with [`vimeo/psalm`](https://psalm.dev), you must use it in order to verify that you use this library correctly.