Initial docs for v2 tool chain

Author: discordier

.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true

.github/workflows/documentation.yml

@@ -0,0 +1,48 @@
+name: Build and deploy documentation
+on:
+  push:
+    branches:
+      - master
+    paths-ignore:
+      - .gitignore
+      - docker-compose.yaml
+      - Makefile
+      - .docker
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name "PHP Code Quality Bot"
+          git config user.email "[email protected]"
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - run: pip install mkdocs-material
+
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -0,0 +1,4 @@
+/.bundle/*
+/gemfiles/*
+/.jekyll-cache/*
+/site

Makefile

@@ -0,0 +1,31 @@
+UID="$(shell id -u)"
+GID="$(shell id -g)"
+
+PROJECT_DIR=$(realpath $(dir $(abspath $(lastword $(MAKEFILE_LIST)))))
+# Replace all special chars in project name.
+# See: https://github.com/docker/compose/issues/2119#issue-109151467
+PROJECT_NAME=$(shell echo $(notdir $(PROJECT_DIR)) | tr A-Z a-z | sed 's/[^a-z0-9]//')
+
+COMPOSE_CMD=WEB_ROOT=$(WEB_ROOT) \
+	UID=${UID} \
+	GID=${GID} \
+	PROJECT_DIR=$(PROJECT_DIR) \
+	docker compose
+
+up:
+	$(COMPOSE_CMD) up -d --renew-anon-volumes --build --remove-orphans
+
+down:
+	$(COMPOSE_CMD) down
+
+restart:
+	$(COMPOSE_CMD) restart mkdocs
+
+shell:
+	$(COMPOSE_CMD) run --rm -it mkdocs /bin/sh
+
+build:
+	$(COMPOSE_CMD) run --rm -it mkdocs build
+
+logs:
+	$(COMPOSE_CMD) logs -f

doc/assets/img/logo.svg

@@ -0,0 +1,3 @@
+img[alt=logo] {
+    filter: invert(1);
+}

doc/assets/style.css

@@ -0,0 +1,46 @@
+# `completion`
+
+The completion command dumps the shell completion script required to use shell autocompletion (currently only bash
+completion is supported).
+
+Usage: `completion [options] [--] [<shell>]`
+
+## Arguments
+
+`shell`
+
+:   The shell type (e.g. "`bash`"), the value of the `$SHELL` env var will be used if this is not given.
+
+## Options
+
+`--debug`
+:   Tail the completion debug log
+
+`-h, --help`
+:   Display help for the command.
+
+=== "Static installation"
+
+    Dump the script to a global completion file and restart your shell:
+    ```
+    bin/phpcq completion bash | sudo tee /etc/bash_completion.d/phpcq
+    ```
+
+    Or dump the script to a local file and source it:
+    ```
+    bin/phpcq completion bash > completion.sh
+    ```
+    Now either source the file whenever you use the project
+    ```
+    source completion.sh
+    ```
+    or add this line at the end of your "`~/.bashrc`" file:
+    ```
+    source /path/to/completion.sh
+    ```
+
+=== "Dynamic installation"
+Add this to the end of your shell configuration file (e.g. "~/.bashrc"):
+```
+eval "$(/path/to/bin/phpcq completion bash)"
+```

doc/command-reference/completion.md

@@ -0,0 +1,34 @@
+# `exec`
+
+Execute a tool with the passed arguments.
+
+The executable tool names are provided by exec task plugins.
+
+Usage: `exec [options] [--] [<application> [<args>...]]`
+
+## Arguments
+
+`application`
+:   The name of the tool that should be executed. You can obtain a list of available tools by invoking `exec --help`.
+
+`args`
+:   Optional options and arguments to pass to the tool - the nature of available arguments and options depends on the
+    tool being invoked.
+
+## Options
+
+`-c, --config=CONFIG`
+:   The configuration file to use.
+
+    If not given, the following filenames are tried (in the current working directory):
+
+    - `.phpcq.yaml`
+    - `phpcq.yaml`
+    - `.phpcq.yaml.dist`
+    - `phpcq.yaml.dist`
+
+`--home-dir=HOME-DIR`
+:   Path to the phpcq home directory (default: `$(CWD)/.phpcq`)
+
+`--ignore-platform-reqs`
+:   Ignore platform requirements (`php` & `ext-` packages).

doc/command-reference/exec.md

@@ -0,0 +1,19 @@
+# global options
+
+We have some options that are globally available in all commands.
+
+`-q, --quiet`
+:   Do not output any message.
+
+`--ansi|--no-ansi`
+:   Force (or disable in case of `--no-ansi`) ANSI output.
+
+`-n, --no-interaction`
+:   Do not ask any interactive question. This will make any command relying on input fail.
+
+`-v|vv|vvv, --verbose`
+:   Increase the verbosity of messages, can be passed up to three times:
+
+    - 1 for normal output
+    - 2 for more verbose output and
+    - 3 for debug

doc/command-reference/global-options.md

@@ -0,0 +1,23 @@
+# Command reference
+
+In this section we provide an overview of all cli commands you can use.
+
+| Command                | abstract                                                              |
+|------------------------|-----------------------------------------------------------------------|
+| [completion]           | Dump the shell completion script required to use shell autocompletion |
+| [exec]                 | Execute a tool with the passed arguments                              |
+| [install]              | Install the phpcq installation from `.phpcq.lock` file                |
+| [platform-information] | Show platform information                                             |
+| [run]                  | Run a configured build task                                           |
+| [self-update]          | Update the phpcq phar file                                            |
+| [update]               | Update the phpcq installation (tools and plugins)                     |
+| [validate]             | Validate the phpcq installation                                       |
+
+[completion]: completion.md
+[exec]: exec.md
+[install]: install.md
+[platform-information]: platform-information.md
+[run]: run.md
+[self-update]: self-update.md
+[update]: update.md
+[validate]: validate.md