Skip to content

Commit c698f39

Browse files
BaptouuuuBaptouuuu
authored
Merge pull request #19 from Innmind/mkdocs
Use MkDocs to publish a documentation website
2 parents 943f84f + 3b2deb2 commit c698f39

27 files changed

+1027
-650
lines changed

‎.github/workflows/documentation.yml

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: ci
2+
on:
3+
push:
4+
branches: [master]
5+
permissions:
6+
contents: write
7+
jobs:
8+
deploy:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
- name: Configure Git Credentials
13+
run: |
14+
git config user.name github-actions[bot]
15+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
16+
- uses: actions/setup-python@v5
17+
with:
18+
python-version: 3.x
19+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
20+
- uses: actions/cache@v4
21+
with:
22+
key: mkdocs-material-${{ env.cache_id }}
23+
path: .cache
24+
restore-keys: |
25+
mkdocs-material-
26+
- run: pip install mkdocs-material
27+
- run: mkdocs gh-deploy --force

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
composer.lock
22
vendor
3+
.cache

‎Makefile

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

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
A set of classes to wrap PHP primitives to build immutable data.
88

9-
[Documentation](docs/README.md)
9+
[Documentation](https://innmind.github.io/Immutable/)
1010

1111
## Installation
1212

‎docs/MONOIDS.md

+9
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,17 @@
1+
---
2+
hide:
3+
- navigation
4+
- toc
5+
---
6+
17
# Monoids
28

39
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)`.
410

511
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).
612

713
This library comes with a few monoids:
14+
815
- `Innmind\Immutable\Monoid\Concat` to append 2 instances of `Innmind\Immutable\Str` together
916
- `Innmind\Immutable\Monoid\Append` to append 2 instances of `Innmind\Immutable\Sequence` together
1017
- `Innmind\Immutable\Monoid\MergeSet` to append 2 instances of `Innmind\Immutable\Set` together
@@ -38,3 +45,5 @@ return static function() {
3845
}
3946
};
4047
```
48+
49+
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

+7
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
1+
---
2+
hide:
3+
- navigation
4+
- toc
5+
---
6+
17
# Philosophy
28

39
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:
10+
411
- higher order functions on data structures
512
- immutability
613

‎docs/README.md

+6-28
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
hide:
3+
- navigation
4+
- toc
5+
---
6+
17
# Getting Started
28

39
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
915
```sh
1016
composer require innmind/immutable
1117
```
12-
13-
## Structures
14-
15-
This library provides the 10 following structures:
16-
17-
- [`Sequence`](SEQUENCE.md)
18-
- [`Set`](SET.md)
19-
- [`Map`](MAP.md)
20-
- [`Str`](STR.md)
21-
- [`RegExp`](REGEXP.md)
22-
- [`Maybe`](MAYBE.md)
23-
- [`Either`](EITHER.md)
24-
- [`Validation`](VALIDATION.md)
25-
- [`State`](STATE.md)
26-
- [`Fold`](FOLD.md)
27-
28-
See the documentation for each structure to understand how to use them.
29-
30-
All structures are typed with [`vimeo/psalm`](https://psalm.dev), you must use it in order to verify that you use this library correctly.
31-
32-
## Use cases
33-
34-
- [How to read a file](LAZY_FILE.md)
35-
- [Parsing strings](PARSING.md)
36-
37-
## Testing
38-
39-
This package provides sets that can be used with [BlackBox](BLACKBOX.md).

‎docs/assets/favicon.png

2.26 KB
Loading

‎docs/assets/fonts/MonaspaceNeon-Regular.woff

46.2 KB
Binary file not shown.

‎docs/assets/logo.svg

+24
Loading

‎docs/assets/stylesheets/extra.css

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
@font-face {
2+
font-family: "Monaspace Neon";
3+
font-weight: normal;
4+
font-style: normal;
5+
src: url("../fonts/MonaspaceNeon-Regular.woff");
6+
}
7+
8+
:root {
9+
--md-code-font: "Monaspace Neon";
10+
}
11+
12+
:root {
13+
--light-md-code-hl-number-color: #f76d47;
14+
--light-md-code-hl-function-color: #6384b9;
15+
--light-md-code-hl-operator-color: #39adb5;
16+
--light-md-code-hl-constant-color: #7c4dff;
17+
--light-md-code-hl-string-color: #9fc06f;
18+
--light-md-code-hl-punctuation-color: #39adb5;
19+
--light-md-code-hl-keyword-color: #7c4dff;
20+
--light-md-code-hl-variable-color: #80cbc4;
21+
--light-md-code-hl-comment-color: #ccd7da;
22+
--light-md-code-bg-color: #fafafa;
23+
--light-md-code-fg-color: #ffb62c;
24+
--light-md-code-hl-variable-color: #6384b9;
25+
--dark-md-code-hl-number-color: #f78c6c;
26+
--dark-md-code-hl-function-color: #82aaff;
27+
--dark-md-code-hl-operator-color: #89ddff;
28+
--dark-md-code-hl-constant-color: #c792ea;
29+
--dark-md-code-hl-string-color: #c3e88d;
30+
--dark-md-code-hl-punctuation-color: #89ddff;
31+
--dark-md-code-hl-keyword-color: #c792ea;
32+
--dark-md-code-hl-variable-color: #e8f9f9;
33+
--dark-md-code-hl-comment-color: #546e7a;
34+
--dark-md-code-bg-color: #263238;
35+
--dark-md-code-fg-color: #ffcb6b;
36+
--dark-md-code-hl-variable-color: #82aaff;
37+
}
38+
39+
@media (prefers-color-scheme: light) {
40+
.language-php > * {
41+
--md-code-hl-number-color: var(--light-md-code-hl-number-color);
42+
--md-code-hl-function-color: var(--light-md-code-hl-function-color);
43+
--md-code-hl-operator-color: var(--light-md-code-hl-operator-color);
44+
--md-code-hl-constant-color: var(--light-md-code-hl-constant-color);
45+
--md-code-hl-string-color: var(--light-md-code-hl-string-color);
46+
--md-code-hl-punctuation-color: var(--light-md-code-hl-punctuation-color);
47+
--md-code-hl-keyword-color: var(--light-md-code-hl-keyword-color);
48+
--md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
49+
--md-code-hl-comment-color: var(--light-md-code-hl-comment-color);
50+
--md-code-bg-color: var(--light-md-code-bg-color);
51+
--md-code-fg-color: var(--light-md-code-fg-color);
52+
}
53+
54+
.language-php .na {
55+
--md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
56+
}
57+
}
58+
59+
[data-md-color-media="(prefers-color-scheme: light)"] .language-php > * {
60+
--md-code-hl-number-color: var(--light-md-code-hl-number-color);
61+
--md-code-hl-function-color: var(--light-md-code-hl-function-color);
62+
--md-code-hl-operator-color: var(--light-md-code-hl-operator-color);
63+
--md-code-hl-constant-color: var(--light-md-code-hl-constant-color);
64+
--md-code-hl-string-color: var(--light-md-code-hl-string-color);
65+
--md-code-hl-punctuation-color: var(--light-md-code-hl-punctuation-color);
66+
--md-code-hl-keyword-color: var(--light-md-code-hl-keyword-color);
67+
--md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
68+
--md-code-hl-comment-color: var(--light-md-code-hl-comment-color);
69+
--md-code-bg-color: var(--light-md-code-bg-color);
70+
--md-code-fg-color: var(--light-md-code-fg-color);
71+
}
72+
73+
[data-md-color-media="(prefers-color-scheme: light)"] .language-php .na {
74+
--md-code-hl-variable-color: var(--light-md-code-hl-variable-color);
75+
}
76+
77+
@media (prefers-color-scheme: dark) {
78+
.language-php > * {
79+
--md-code-hl-number-color: var(--dark-md-code-hl-number-color);
80+
--md-code-hl-function-color: var(--dark-md-code-hl-function-color);
81+
--md-code-hl-operator-color: var(--dark-md-code-hl-operator-color);
82+
--md-code-hl-constant-color: var(--dark-md-code-hl-constant-color);
83+
--md-code-hl-string-color: var(--dark-md-code-hl-string-color);
84+
--md-code-hl-punctuation-color: var(--dark-md-code-hl-punctuation-color);
85+
--md-code-hl-keyword-color: var(--dark-md-code-hl-keyword-color);
86+
--md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
87+
--md-code-hl-comment-color: var(--dark-md-code-hl-comment-color);
88+
--md-code-bg-color: var(--dark-md-code-bg-color);
89+
--md-code-fg-color: var(--dark-md-code-fg-color);
90+
}
91+
92+
.language-php .na {
93+
--md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
94+
}
95+
}
96+
97+
[data-md-color-media="(prefers-color-scheme: dark)"] .language-php > * {
98+
--md-code-hl-number-color: var(--dark-md-code-hl-number-color);
99+
--md-code-hl-function-color: var(--dark-md-code-hl-function-color);
100+
--md-code-hl-operator-color: var(--dark-md-code-hl-operator-color);
101+
--md-code-hl-constant-color: var(--dark-md-code-hl-constant-color);
102+
--md-code-hl-string-color: var(--dark-md-code-hl-string-color);
103+
--md-code-hl-punctuation-color: var(--dark-md-code-hl-punctuation-color);
104+
--md-code-hl-keyword-color: var(--dark-md-code-hl-keyword-color);
105+
--md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
106+
--md-code-hl-comment-color: var(--dark-md-code-hl-comment-color);
107+
--md-code-bg-color: var(--dark-md-code-bg-color);
108+
--md-code-fg-color: var(--dark-md-code-fg-color);
109+
}
110+
111+
[data-md-color-media="(prefers-color-scheme: dark)"] .language-php .na {
112+
--md-code-hl-variable-color: var(--dark-md-code-hl-variable-color);
113+
}

‎docs/EITHER.md ‎docs/structures/either.md

+22-14
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ function accessResource(User $user): Either {
3232
}
3333
```
3434

35-
> **Note**
36-
> `ServerRequest`, `User`, `Resource` and `Error` are imaginary classes.
35+
!!! note ""
36+
`ServerRequest`, `User`, `Resource` and `Error` are imaginary classes.
3737

3838
## `::left()`
3939

@@ -43,8 +43,8 @@ This builds an `Either` instance with the given value in the left hand side.
4343
$either = Either::left($anyValue);
4444
```
4545

46-
> **Note**
47-
> usually this side is used for errors.
46+
!!! note ""
47+
Usually this side is used for errors.
4848

4949
## `::right()`
5050

@@ -54,8 +54,8 @@ This builds an `Either` instance with the given value in the right hand side.
5454
$either = Either::right($anyValue);
5555
```
5656

57-
> **Note**
58-
> usually this side is used for valid values.
57+
!!! note ""
58+
Usually this side is used for valid values.
5959

6060
## `::defer()`
6161

@@ -75,7 +75,8 @@ $either = Either::defer(static function() {
7575

7676
Methods called (except `match`) on a deferred `Either` will not be called immediately but will be composed to be executed once you call `match`.
7777

78-
> **Warning** this means that if you never call `match` on a deferred `Either` it will do nothing.
78+
!!! warning ""
79+
This means that if you never call `match` on a deferred `Either` it will do nothing.
7980

8081
## `->map()`
8182

@@ -85,7 +86,9 @@ This will apply the map transformation on the right value if there is one, other
8586
/** @var Either<Error, User> */
8687
$either = identify($serverRequest);
8788
/** @var Either<Error, Impersonated> */
88-
$impersonated = $either->map(fn(User $user): Impersonated => $user->impersonateAdmin());
89+
$impersonated = $either->map(
90+
fn(User $user): Impersonated => $user->impersonateAdmin(),
91+
);
8992
```
9093

9194
## `->flatMap()`
@@ -109,12 +112,14 @@ $response = identify($serverRequest)
109112
->flatMap(fn(User $user): Either => accessResource($user))
110113
->match(
111114
fn(Resource $resource) => new Response(200, $resource->toString()),
112-
fn(Error $error) => new Response(400, $error->message()), // here the error can be from identify or from accessResource
115+
fn(Error $error) => new Response(400, $error->message()), //(1)
113116
);
114117
```
115118

116-
> **Note**
117-
> `Response` is an imaginary class.
119+
1. Here the error can be from `identify` or from `accessResource`.
120+
121+
!!! note ""
122+
`Response` is an imaginary class.
118123

119124
## `->otherwise()`
120125

@@ -148,11 +153,14 @@ identify($request)
148153
fn() => new Error('User is not allowed'),
149154
)
150155
->match(
151-
fn(User $user) => doSomething($user), // here we know the user is allowed
152-
fn(Error $error) => print($error->message()), // can be "User not found" or "User is not allowed"
156+
fn(User $user) => doSomething($user), //(1)
157+
fn(Error $error) => print($error->message()), //(2)
153158
);
154159
```
155160

161+
1. Here we know the user is allowed.
162+
2. Can be "User not found" or "User is not allowed".
163+
156164
## `->leftMap()`
157165

158166
This is similar to the `->map()` function but will be applied on the left value only.
@@ -165,7 +173,7 @@ $either = identify($request)
165173

166174
## `->maybe()`
167175

168-
This returns a [`Maybe`](MAYBE.md) containing the right value, in case of a left value it returns a `Maybe` with nothing inside.
176+
This returns a [`Maybe`](maybe.md) containing the right value, in case of a left value it returns a `Maybe` with nothing inside.
169177

170178
```php
171179
Either::right('something')->maybe()->match(

‎docs/FOLD.md ‎docs/structures/fold.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# `Fold`
22

3-
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.
3+
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.
44

55
An example is reading from a socket as it's an infinite stream of strings:
66

‎docs/structures/index.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Structures
2+
3+
This library provides the 10 following structures:
4+
5+
- [`Sequence`](sequence.md)
6+
- [`Set`](set.md)
7+
- [`Map`](map.md)
8+
- [`Str`](str.md)
9+
- [`RegExp`](regexp.md)
10+
- [`Maybe`](maybe.md)
11+
- [`Either`](either.md)
12+
- [`Validation`](validation.md)
13+
- [`State`](state.md)
14+
- [`Fold`](fold.md)
15+
16+
See the documentation for each structure to understand how to use them.
17+
18+
All structures are typed with [`vimeo/psalm`](https://psalm.dev), you must use it in order to verify that you use this library correctly.

0 commit comments

Comments
 (0)