Create readthedocs documentation

docs/.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+    os: ubuntu-24.04
+    tools:
+        python: "3.13"
+    jobs:
+        pre_install:
+            - pip install mkdocs-material
+
+mkdocs:
+    configuration: docs/mkdocs.yml
+
+python:
+    install:
+        - requirements: docs/requirements.txt

docs/assets/css/theme.css

@@ -0,0 +1,44 @@
+body {
+    cursor: default;
+}
+
+h1 {
+    margin-bottom: 0.5em !important;
+    color: #4051B5 !important;
+    font-weight: 500 !important;
+}
+
+h2 {
+    margin-top: 0.5em !important;
+    margin-bottom: 0.5em !important;
+    color: #4051B5 !important;
+    font-size: 1.3em;
+}
+
+div.md-main__inner {
+    margin-top: 0;
+}
+
+:root {
+    --md-typeset-a-color: #30a2a9;
+}
+
+.icon-green {
+    color: #069006;
+}
+
+.md-typeset .admonition > .admonition-title {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+}
+
+.tryit-link {
+    margin-left: auto;
+}
+
+li.md-nav__item--active > label.md-nav__link > span.md-ellipsis,
+li.md-nav__item--active > label.md-nav__link > span.md-nav__icon
+{
+    color: var(--md-typeset-a-color);
+}

docs/assets/js/readthedocs-search.js

@@ -0,0 +1,6 @@
+document.addEventListener("DOMContentLoaded", function(event) {
+    document.querySelector(".md-search__input").addEventListener("focus", (e) => {
+        const event = new CustomEvent("readthedocs-search-show");
+        document.dispatchEvent(event);
+    });
+});

docs/assets/js/try-it.js

@@ -0,0 +1,11 @@
+document.addEventListener("DOMContentLoaded", () => {
+    document.querySelectorAll(".admonition .admonition-title").forEach(title => {
+        if (title.textContent.trim() === "Try it!") {
+            const link = document.createElement("a");
+            link.href = "/en/latest/examples/available-examples";
+            link.className = "tryit-link";
+            link.textContent = "How to execute examples";
+            title.appendChild(link);
+        }
+    });
+});

docs/contributing/tips-for-devs.md

@@ -0,0 +1,33 @@
+---
+hide:
+  - toc
+---
+
+# Work on the code
+
+You can clone the project:
+```bash
+git clone git@github.com:steevanb/php-parallel-processes.git
+```
+
+Then, when you to execute your local code, you need to add a volume on `/composer/vendor/steevanb/php-parallel-processes`:
+```bash hl_lines="6"
+docker \
+    run \
+        --rm \
+        -it \
+        -v "$(pwd)":/app \
+        -v "$(pwd)":/composer/vendor/steevanb/php-parallel-processes \
+        steevanb/php-parallel-processes:{{ package_version }}-alpine \
+            php /app/parallel-processes.php
+```
+
+# Work on the documentation
+
+We use [readthedocs](https://about.readthedocs.com/), 
+[mkdocs](https://docs.readthedocs.com/platform/stable/intro/mkdocs.html) 
+and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference).
+
+Documentation is written in Markdown in [docs/](https://github.com/steevanb/php-parallel-processes/tree/readthedocs/docs).
+
+See [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/) for Markdown syntaxes and examples.

docs/examples/available-examples.md

@@ -0,0 +1,28 @@
+---
+hide:
+  - toc
+---
+
+# Available examples
+
+All examples are in [examples/](https://github.com/steevanb/php-parallel-processes/tree/master/examples).
+
+# How to execute an example
+
+You need to download the latest version of [parallel-processes-example.sh](https://raw.githubusercontent.com/steevanb/php-parallel-processes/refs/heads/master/examples/parallel-processes-example.sh).
+
+`parallel-processes-example.sh` has one mandatory argument: the path to the example, after `examples/` directory:
+```bash
+parallel-processes-example.sh path/to/example.php
+```
+
+# Configure an example
+
+Some of them can be configured with env vars.
+
+All configuration are prefixed by `PP_`.
+
+```bash hl_lines="1"
+PP_CANCELED_AS_ERROR=true \
+    parallel-processes-example.sh usage/process-configuration/canceled-as-error.php
+```

docs/getting-started/license.md

@@ -0,0 +1,11 @@
+---
+hide:
+  - toc
+---
+
+# License
+
+`parallel-processes` is licensed under the [Apache 2.0 License](https://github.com/steevanb/php-parallel-processes/blob/master/LICENSE).
+
+The Apache 2.0 license allows you to freely use, modify, and distribute software, including for commercial purposes,
+as long as you keep the copyright and license notices and indicate any changes made.

docs/index.md

@@ -0,0 +1,76 @@
+---
+hide:
+  - toc
+---
+
+# Presentation
+
+`parallel-processes` is an open-source PHP library for running multiple processes in parallel.
+
+![Parallel Processes demo](assets/images/demo.gif)
+
+# Key features
+
+<div class="grid cards" markdown>
+
+-   :material-docker:{ .lg .middle } __Install it or use Docker images__
+
+    ---
+
+    Install it as a Composer dependency or use the provided Docker images to avoid a local installation.
+
+    [:octicons-arrow-right-24: Installation](installation/composer-dependency.md)
+
+-   :material-file-tree:{ .lg .middle } __Process start rules__
+
+    ---
+
+    Configure when a process should start: immediately, after another process, during bootstrap, or during teardown.
+
+    [:octicons-arrow-right-24: Bootstrap or tear down](usage/bootstrap-tear-down.md)
+
+-   :material-cog-outline:{ .lg .middle } __Process configuration__
+
+    ---
+
+    Configure each process: name, command, maximum execution time, output verbosity, etc.
+
+    [:octicons-arrow-right-24: Configure process](usage/process-configuration/miscellaneous.md)
+
+-   :material-cog-outline:{ .lg .middle } __Execution configuration__
+
+    ---
+
+    Configure execution settings for your processes using PHP: process order, refresh interval, timeout, etc.
+
+    [:octicons-arrow-right-24: Minimal configuration](usage/minimal-configuration.md)
+
+-   :material-message-bulleted:{ .lg .middle } __Verbosity__
+
+    ---
+
+    Control output verbosity: show process output, execution time, only errors, or all outputs.
+
+    [:octicons-arrow-right-24: Output verbosity](usage/output-verbosity.md)
+
+-  :material-compare:{ .lg .middle } __Theme__
+
+    ---
+
+    Choose between the Default and Summary themes, or create a custom theme.
+
+    [:octicons-arrow-right-24: Theme configuration](theme/configuration.md)
+
+</div>
+
+# License
+
+`parallel-processes` is licensed under the [Apache 2.0 License](getting-started/license.md).
+
+# Links
+
+GitHub: [steevanb/php-parallel-processes](https://github.com/steevanb/php-parallel-processes)
+
+Docker Hub: [steevanb/php-parallel-processes](https://hub.docker.com/r/steevanb/php-parallel-processes)
+
+Creator: [Steevan BARBOYON](http://prestation.info-droid.fr/)

docs/installation/composer-dependency.md

@@ -0,0 +1,33 @@
+---
+hide:
+  - toc
+---
+
+# Composer dependency
+
+If you want to install `parallel-processses` in your project, with Composer:
+
+```bash
+composer require steevanb/php-parallel-processes:^{{ package_version }}
+```
+
+# Dependencies
+
+<div class="grid cards" markdown>
+
+- :material-penguin: __OS__: Linux and macOS, no tested on Windows
+- :material-language-php: __PHP__: ^8.2
+- :material-symfony: __[symfony/console](https://symfony.com/doc/current/components/console.html)__: ^7.0
+- :material-symfony: __[symfony/process](https://symfony.com/doc/current/components/process.html)__: ^7.0
+
+</div>
+
+# Configure your processes
+
+See [minimal configuration](../usage/minimal-configuration.md).
+
+# Available versions
+
+See [releases](https://github.com/steevanb/php-parallel-processes/releases).
+
+See [changelog](https://github.com/steevanb/php-parallel-processes/blob/master/changelog.md).

docs/installation/docker-image.md

@@ -0,0 +1,106 @@
+---
+hide:
+  - toc
+---
+
+# Use Docker image
+
+`parallel-processses` provide Docker images with everything installed: PHP, the library and Docker.
+
+You can choose between this 3 versions:
+
+* `alpine`: smallest version, but could be "too much simple" sometimes
+* `buster`: middle version, contains almost everything needed
+* `bookworm`: larger version, should contain what you need
+
+# Dependencies
+
+<div class="grid cards" markdown>
+
+- :material-penguin: __OS__: Linux, Windows and macOS
+- :material-docker: __Docker__: you should already have a compatible version
+
+</div>
+
+# Basic usage
+
+See [minimal configuration](../usage/minimal-configuration.md) to create your parallel processes configuration.
+
+Then you can use official images to execute it:
+```bash
+docker \
+    run \
+        --rm \
+        -it \
+        -v "$(pwd)":/app \
+        steevanb/php-parallel-processes:{{ package_version }}-alpine \
+            php /app/parallel-processes.php
+```
+
+# Docker outside of Docker (DooD)
+
+If your processes need to execute Docker commands on your host, you can do it with DooD.
+
+You have to add a volume to your Docker socket, that's all:
+
+```bash hl_lines="6"
+docker \
+    run \
+        --rm \
+        -it \
+        -v "$(pwd)":/app \
+        -v /var/run/docker.sock:/var/run/docker.sock \
+        steevanb/php-parallel-processes:{{ package_version }}-alpine \
+            php /app/parallel-processes.php 
+```
+
+!!! info "docker.sock host path"
+    Use `docker context inspect` to get your socket path if it's not `/var/run/docker.sock`.
+
+    In this case, keep `/var/run/docker.sock` for the volume target.
+
+Examples of processes that use the Docker host's socket:
+```php
+<?php
+
+use Steevanb\ParallelProcess\{
+    Console\Application\ParallelProcessesApplication,
+    Process\Process
+};
+use Symfony\Component\Console\Input\ArgvInput;
+
+require $_ENV['COMPOSER_GLOBAL_AUTOLOAD_FILE_NAME'];
+
+(new ParallelProcessesApplication())
+
+    // This command will be executed in the parallel-processes Docker container,
+    // but it will use the host's Docker socket
+    // It’s almost as if it were executed directly on the host
+    ->addProcess(new Process(['docker', 'build']))
+
+    // You can use Docker compose plugin
+    ->addProcess(new Process(['docker', 'compose', 'build']))
+
+    // You can use Docker buildx plugin, but only with buster and bookworm images
+    // alpine do not contain buildx
+    ->addProcess(new Process(['docker', 'buildx', 'build']))
+
+    ->run(new ArgvInput($argv));
+```
+
+Official images are bundled with Docker and some plugins:
+
+| Image                                                                                                                               |                  docker                   |              compose plugin               |               buildx plugin               |
+|-------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------:|:-----------------------------------------:|:-----------------------------------------:|
+| [{{ package_version }}-alpine](https://hub.docker.com/r/steevanb/php-parallel-processes/tags?name={{ package_version }}-alpine)     | :material-checkbox-marked:{ .icon-green } | :material-checkbox-marked:{ .icon-green } |                                           |
+| [{{ package_version }}-buster](https://hub.docker.com/r/steevanb/php-parallel-processes/tags?name={{ package_version }}-buster)     | :material-checkbox-marked:{ .icon-green } | :material-checkbox-marked:{ .icon-green } | :material-checkbox-marked:{ .icon-green } |
+| [{{ package_version }}-bookworm](https://hub.docker.com/r/steevanb/php-parallel-processes/tags?name={{ package_version }}-bookworm) | :material-checkbox-marked:{ .icon-green } | :material-checkbox-marked:{ .icon-green } | :material-checkbox-marked:{ .icon-green } |
+
+!!! info "Docker is installed since 1.1.0"
+    Docker, compose and buildx plugins are installed in Docker images since `1.1.0`.
+
+# Available versions
+
+See [Docker tags](https://hub.docker.com/r/steevanb/php-parallel-processes/tags).
+
+See [changelog](https://github.com/steevanb/php-parallel-processes/blob/master/changelog.md).