diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..b48389d --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,10 @@ +name: Documentation +on: + push: + branches: [master, main] +permissions: + contents: write +jobs: + deploy: + uses: innmind/github-workflows/.github/workflows/documentation.yml@main + secrets: inherit diff --git a/.gitignore b/.gitignore index ff72e2d..fe80fd5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ /composer.lock /vendor +/.cache diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..6b5c6f1 --- /dev/null +++ b/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 diff --git a/README.md b/README.md index 09c5437..ff8e8a5 100644 --- a/README.md +++ b/README.md @@ -17,16 +17,12 @@ composer require innmind/encoding ## Usage -Take a look at the [documentation](documentation/README.md) for a more in-depth understanding of the possibilities. - -### Creating an archive of a directory - ```php use Innmind\Filesystem\{ Adapter\Filesystem, Name, }; -use Innmind\TimeContinuum\Earth; +use Innmind\TimeContinuum\Clock; use Innmind\Url\Path; use Innmind\Encoding\{ Gzip, @@ -36,7 +32,7 @@ use Innmind\Encoding\{ $adapter = Filesystem::mount(Path::of('some/directory/')); $tar = $adapter ->get(Name::of('data')) - ->map(Tar::encode(new Earth\Clock)) + ->map(Tar::encode(Clock::live())) ->map(Gzip::compress()) ->match( static fn($file) => $file, @@ -44,4 +40,8 @@ $tar = $adapter ); ``` -Here `$tar` represents a `.tar.gz` file containing all the files and directories from `sime/directory/data/`, unless the `data` doesn't exist then it is `null`. +Here `$tar` represents a `.tar.gz` file content containing all the files and directories from `some/directory/data/`, unless the `data` doesn't exist then it is `null`. + +## Documentation + +Full documentation can be found at . diff --git a/documentation/assets/favicon.png b/documentation/assets/favicon.png new file mode 100644 index 0000000..08dee3a Binary files /dev/null and b/documentation/assets/favicon.png differ diff --git a/documentation/assets/fonts/MonaspaceNeon-Regular.woff b/documentation/assets/fonts/MonaspaceNeon-Regular.woff new file mode 100644 index 0000000..ce0168b Binary files /dev/null and b/documentation/assets/fonts/MonaspaceNeon-Regular.woff differ diff --git a/documentation/assets/logo.svg b/documentation/assets/logo.svg new file mode 100644 index 0000000..6a5d322 --- /dev/null +++ b/documentation/assets/logo.svg @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/assets/proof.png b/documentation/assets/proof.png new file mode 100644 index 0000000..31a8f26 Binary files /dev/null and b/documentation/assets/proof.png differ diff --git a/documentation/assets/property.png b/documentation/assets/property.png new file mode 100644 index 0000000..d3b4a88 Binary files /dev/null and b/documentation/assets/property.png differ diff --git a/documentation/assets/stylesheets/extra.css b/documentation/assets/stylesheets/extra.css new file mode 100644 index 0000000..e4aa2d4 --- /dev/null +++ b/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); +} diff --git a/documentation/assets/test.png b/documentation/assets/test.png new file mode 100644 index 0000000..cc1afdc Binary files /dev/null and b/documentation/assets/test.png differ diff --git a/documentation/README.md b/documentation/index.md similarity index 54% rename from documentation/README.md rename to documentation/index.md index 2a2bb20..bfd5795 100644 --- a/documentation/README.md +++ b/documentation/index.md @@ -1,14 +1,16 @@ +--- +hide: + - navigation + - toc +--- + # Getting started This package allows to create `tar` files and compress any file via `gzip` all in memory. This means that you don't have to have the source files written to disk to compress them. This package also work lazily, meaning that you never have to load a whole file in memory allowing you to work with files that may not fit in memory. -Combining this package with the rest of the [Innmind ecosystem](https://github.com/innmind/) unlocks opportunities that weren't possible previously (or at least very hard to achieve). Here are some use cases: - -- [Creating a backup from different sources](use_cases/backup.md) -- [Storing compressed files](use_cases/compressed_at_rest.md) -- [Sending compressed files through HTTP](use_cases/http.md) +Combining this package with the rest of the [Innmind ecosystem](https://github.com/innmind/) unlocks opportunities that weren't possible previously (or at least very hard to achieve). -> **Note** -> All use cases use the [`innmind/operating-system`](https://packagist.org/packages/innmind/operating-system) package. +!!! note "" + All use cases use the [`innmind/operating-system`](https://packagist.org/packages/innmind/operating-system) package. diff --git a/documentation/use_cases/backup.md b/documentation/use-cases/backup.md similarity index 78% rename from documentation/use_cases/backup.md rename to documentation/use-cases/backup.md index f16592c..a5c9363 100644 --- a/documentation/use_cases/backup.md +++ b/documentation/use-cases/backup.md @@ -49,7 +49,7 @@ $archive = Gzip::compress()( ); ``` -Up to this point `$archive` represents a file named `archive.tar.gz` but no real operation has been done. For the real compression to happen you need to _unwrap_ the file either by persisting to the filesystem, sending it through HTTP/AMQP or returning it as an HTTP response. Here's an example of a simple file responding to an HTTP request: +Up to this point `$archive` represents a file content but no real operation has been done. For the real compression to happen you need to _unwrap_ the file either by persisting to the filesystem, sending it through HTTP/AMQP or returning it as an HTTP response. Here's an example of a simple file responding to an HTTP request: ```php use Innmind\Http\{ @@ -63,13 +63,13 @@ use Innmind\Http\{ $archive = /* see above */; -(new ResponseSender($os->clock))(Response::of( +(new ResponseSender($os->clock()))(Response::of( StatusCode::ok, ProtocolVersion::v11, Headers::of( ContentType::of('application', 'octet-stream') ), - $archive->content(), + $archive, )); ``` diff --git a/documentation/use_cases/compressed_at_rest.md b/documentation/use-cases/compressed-at-rest.md similarity index 100% rename from documentation/use_cases/compressed_at_rest.md rename to documentation/use-cases/compressed-at-rest.md diff --git a/documentation/use_cases/http.md b/documentation/use-cases/http.md similarity index 100% rename from documentation/use_cases/http.md rename to documentation/use-cases/http.md diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..eb84c53 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,99 @@ +site_name: Innmind/encoding +repo_name: Innmind/encoding +docs_dir: documentation + +nav: + - Getting Started: index.md + - Use cases: + - use-cases/backup.md + - use-cases/compressed-at-rest.md + - use-cases/http.md + +theme: + name: material + logo: assets/logo.svg + favicon: assets/favicon.png + font: false + features: + - content.code.copy + - content.code.annotate + - navigation.tracking + - navigation.tabs + - navigation.tabs.sticky + - navigation.sections + - navigation.expand + - navigation.indexes + - navigation.top + - navigation.footer + - search.suggest + - search.highlight + - content.action.edit + palette: + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + primary: blue + accent: deep orange + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + primary: blue + accent: deep orange + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to system preference + primary: blue + accent: deep orange + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + extend_pygments_lang: + - name: php + lang: php + options: + startinline: true + - pymdownx.inlinehilite + - pymdownx.snippets + - attr_list + - md_in_html + - pymdownx.superfences + - abbr + - admonition + - pymdownx.details: + - pymdownx.tabbed: + alternate_style: true + - toc: + permalink: true + - footnotes + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + +extra_css: + - assets/stylesheets/extra.css + +plugins: + - search + - privacy + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/Innmind/encoding + - icon: fontawesome/brands/x-twitter + link: https://twitter.com/Baptouuuu + - icon: fontawesome/brands/mastodon + link: https://phpc.social/@baptouuuu + - icon: fontawesome/brands/bluesky + link: https://bsky.app/profile/baptouuuu.bsky.social