Skip to content

Commit 0d14f5f

Browse files
discordierdiscordier
committed
Initial docs for v2 tool chain
0 parents  commit 0d14f5f

36 files changed

+1042
-0
lines changed

‎.editorconfig

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
indent_style = space
6+
indent_size = 2
7+
end_of_line = lf
8+
insert_final_newline = true
9+
trim_trailing_whitespace = true

‎.github/workflows/documentation.yml

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Build and deploy documentation
2+
on:
3+
push:
4+
branches:
5+
- master
6+
paths-ignore:
7+
- .gitignore
8+
- docker-compose.yaml
9+
- Makefile
10+
- .docker
11+
# Allows you to run this workflow manually from the Actions tab
12+
workflow_dispatch:
13+
14+
permissions:
15+
contents: write
16+
17+
# Allow one concurrent deployment
18+
concurrency:
19+
group: "pages"
20+
cancel-in-progress: true
21+
22+
jobs:
23+
deploy:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- uses: actions/checkout@v4
27+
28+
- name: Configure Git Credentials
29+
run: |
30+
git config user.name "PHP Code Quality Bot"
31+
git config user.email "[email protected]"
32+
33+
- uses: actions/setup-python@v4
34+
with:
35+
python-version: 3.x
36+
37+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
38+
39+
- uses: actions/cache@v3
40+
with:
41+
key: mkdocs-material-${{ env.cache_id }}
42+
path: .cache
43+
restore-keys: |
44+
mkdocs-material-
45+
46+
- run: pip install mkdocs-material
47+
48+
- run: mkdocs gh-deploy --force

‎.gitignore

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
/.bundle/*
2+
/gemfiles/*
3+
/.jekyll-cache/*
4+
/site

‎Makefile

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
UID="$(shell id -u)"
2+
GID="$(shell id -g)"
3+
4+
PROJECT_DIR=$(realpath $(dir $(abspath $(lastword $(MAKEFILE_LIST)))))
5+
# Replace all special chars in project name.
6+
# See: https://github.com/docker/compose/issues/2119#issue-109151467
7+
PROJECT_NAME=$(shell echo $(notdir $(PROJECT_DIR)) | tr A-Z a-z | sed 's/[^a-z0-9]//')
8+
9+
COMPOSE_CMD=WEB_ROOT=$(WEB_ROOT) \
10+
UID=${UID} \
11+
GID=${GID} \
12+
PROJECT_DIR=$(PROJECT_DIR) \
13+
docker compose
14+
15+
up:
16+
$(COMPOSE_CMD) up -d --renew-anon-volumes --build --remove-orphans
17+
18+
down:
19+
$(COMPOSE_CMD) down
20+
21+
restart:
22+
$(COMPOSE_CMD) restart mkdocs
23+
24+
shell:
25+
$(COMPOSE_CMD) run --rm -it mkdocs /bin/sh
26+
27+
build:
28+
$(COMPOSE_CMD) run --rm -it mkdocs build
29+
30+
logs:
31+
$(COMPOSE_CMD) logs -f

‎doc/assets/img/logo.svg

+1
Loading

‎doc/assets/style.css

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
img[alt=logo] {
2+
filter: invert(1);
3+
}

‎doc/command-reference/completion.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# `completion`
2+
3+
The completion command dumps the shell completion script required to use shell autocompletion (currently only bash
4+
completion is supported).
5+
6+
Usage: `completion [options] [--] [<shell>]`
7+
8+
## Arguments
9+
10+
`shell`
11+
12+
: The shell type (e.g. "`bash`"), the value of the `$SHELL` env var will be used if this is not given.
13+
14+
## Options
15+
16+
`--debug`
17+
: Tail the completion debug log
18+
19+
`-h, --help`
20+
: Display help for the command.
21+
22+
=== "Static installation"
23+
24+
Dump the script to a global completion file and restart your shell:
25+
```
26+
bin/phpcq completion bash | sudo tee /etc/bash_completion.d/phpcq
27+
```
28+
29+
Or dump the script to a local file and source it:
30+
```
31+
bin/phpcq completion bash > completion.sh
32+
```
33+
Now either source the file whenever you use the project
34+
```
35+
source completion.sh
36+
```
37+
or add this line at the end of your "`~/.bashrc`" file:
38+
```
39+
source /path/to/completion.sh
40+
```
41+
42+
=== "Dynamic installation"
43+
Add this to the end of your shell configuration file (e.g. "~/.bashrc"):
44+
```
45+
eval "$(/path/to/bin/phpcq completion bash)"
46+
```

‎doc/command-reference/exec.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# `exec`
2+
3+
Execute a tool with the passed arguments.
4+
5+
The executable tool names are provided by exec task plugins.
6+
7+
Usage: `exec [options] [--] [<application> [<args>...]]`
8+
9+
## Arguments
10+
11+
`application`
12+
: The name of the tool that should be executed. You can obtain a list of available tools by invoking `exec --help`.
13+
14+
`args`
15+
: Optional options and arguments to pass to the tool - the nature of available arguments and options depends on the
16+
tool being invoked.
17+
18+
## Options
19+
20+
`-c, --config=CONFIG`
21+
: The configuration file to use.
22+
23+
If not given, the following filenames are tried (in the current working directory):
24+
25+
- `.phpcq.yaml`
26+
- `phpcq.yaml`
27+
- `.phpcq.yaml.dist`
28+
- `phpcq.yaml.dist`
29+
30+
`--home-dir=HOME-DIR`
31+
: Path to the phpcq home directory (default: `$(CWD)/.phpcq`)
32+
33+
`--ignore-platform-reqs`
34+
: Ignore platform requirements (`php` & `ext-` packages).

‎doc/command-reference/global-options.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# global options
2+
3+
We have some options that are globally available in all commands.
4+
5+
`-q, --quiet`
6+
: Do not output any message.
7+
8+
`--ansi|--no-ansi`
9+
: Force (or disable in case of `--no-ansi`) ANSI output.
10+
11+
`-n, --no-interaction`
12+
: Do not ask any interactive question. This will make any command relying on input fail.
13+
14+
`-v|vv|vvv, --verbose`
15+
: Increase the verbosity of messages, can be passed up to three times:
16+
17+
- 1 for normal output
18+
- 2 for more verbose output and
19+
- 3 for debug

‎doc/command-reference/index.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Command reference
2+
3+
In this section we provide an overview of all cli commands you can use.
4+
5+
| Command | abstract |
6+
|------------------------|-----------------------------------------------------------------------|
7+
| [completion] | Dump the shell completion script required to use shell autocompletion |
8+
| [exec] | Execute a tool with the passed arguments |
9+
| [install] | Install the phpcq installation from `.phpcq.lock` file |
10+
| [platform-information] | Show platform information |
11+
| [run] | Run a configured build task |
12+
| [self-update] | Update the phpcq phar file |
13+
| [update] | Update the phpcq installation (tools and plugins) |
14+
| [validate] | Validate the phpcq installation |
15+
16+
[completion]: completion.md
17+
[exec]: exec.md
18+
[install]: install.md
19+
[platform-information]: platform-information.md
20+
[run]: run.md
21+
[self-update]: self-update.md
22+
[update]: update.md
23+
[validate]: validate.md

‎doc/command-reference/install.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# `install`
2+
3+
Install the phpcq installation from existing `.phpcq.lock` file.
4+
5+
If no `.phpcq.lock` file has been created yet, the `install` command behaves like the [`update`](update.md) command.
6+
7+
### Options
8+
9+
Options:
10+
11+
`-d, --dry-run`
12+
: Dry run
13+
14+
`-x, --cache=CACHE`
15+
: Path to the phpcq cache directory (default: `/$(HOME)/.cache/phpcq`)
16+
17+
`-k, --trust-keys`
18+
: Add all keys to trusted key storage (**discouraged!**)
19+
20+
`-c, --config=CONFIG`
21+
: The configuration file to use.
22+
23+
If not given, the following filenames are tried (in the current working directory):
24+
25+
- `.phpcq.yaml`
26+
- `phpcq.yaml`
27+
- `.phpcq.yaml.dist`
28+
- `phpcq.yaml.dist`
29+
30+
`--home-dir=HOME-DIR`
31+
: Path to the phpcq home directory (default: `$(CWD)/.phpcq`)
32+
33+
`--ignore-platform-reqs`
34+
: Ignore platform requirements (`php` & `ext-` packages).

‎doc/command-reference/platform-information.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# `platform-information`
2+
3+
Shows platform information.
4+
5+
This lists the following platform information as ASCII table:
6+
7+
- PHP Version.
8+
- Names of enabled PHP extensions and their version.
9+
- Names of linked libraries and their version.

‎doc/command-reference/run.md

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# `run`
2+
3+
This command runs a configured build task.
4+
5+
Should the task fail, it will be reported with a non-zero exit code (unless option `--exit-0` has been passed).
6+
7+
If the passed task name is a chain, all tasks will get executed in sequential order and the result will get logged.
8+
9+
### Arguments
10+
11+
`task`
12+
: Define a specific task which should be run (default: `default`)
13+
14+
### Options
15+
16+
17+
`--exit-0`
18+
: Forces the exit code to 0 - this is useful to "ignore" failures in CI as "allow-failure" mode.
19+
20+
`-r, --report=REPORT`
21+
: Set the report format(s) that shall be created (default: `file-report`).
22+
23+
This can be passed multiple times.
24+
25+
Available options are:
26+
27+
- `file-report` - an xml file tracking violations organized by files.
28+
- `task-report` - an xml file tracking violations organized by check tasks.
29+
- `checkstyle` - [checkstyle](https://checkstyle.org/) compatible XML output which is used by many tools.
30+
31+
`-o, --output=OUTPUT`
32+
: Set a specific console output format (default: `default`).
33+
34+
This can be passed multiple times.
35+
36+
Available options are:
37+
38+
- `default` - The default phpcq output.
39+
- `github-action` - Github action compatible output.
40+
41+
`--threshold=THRESHOLD`
42+
: Set the minimum threshold for diagnostics to be reported - any severity below this will not get reported (default:
43+
`marginal`).
44+
45+
Available options are (in ascending order):
46+
47+
- `none`
48+
- `info`
49+
- `minor`
50+
- `marginal`
51+
- `major`
52+
- `fatal`
53+
54+
`-j, --threads=THREADS`
55+
: Set the amount of threads to run in parallel (default: `nproc`).
56+
57+
The allowed values range from `1` (single thread) to the amount of available logical processors (if it can be
58+
determined)
59+
60+
`-c, --config=CONFIG`
61+
: The configuration file to use.
62+
63+
If not given, the following filenames are tried (in the current working directory):
64+
65+
- .phpcq.yml
66+
- phpcq.yml
67+
- .phpcq.yml.dist
68+
- phpcq.yml.dist
69+
70+
`--home-dir=HOME-DIR`
71+
: Path to the phpcq home directory (default: `$(CWD)/.phpcq`)
72+
73+
`--ignore-platform-reqs`
74+
: Ignore platform requirements (`php` & `ext-` packages).
75+
76+
`-ff, --fast-finish`
77+
: Do not keep going and execute all tasks but break on first error.

‎doc/command-reference/self-update.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# `self-update`
2+
3+
Updates the phpcq phar file
4+
5+
### Options
6+
7+
`-c, --config=CONFIG`
8+
: The configuration file to use.
9+
10+
If not given, the following filenames are tried (in the current working directory):
11+
12+
- .phpcq.yml
13+
- phpcq.yml
14+
- .phpcq.yml.dist
15+
- phpcq.yml.dist
16+
17+
`--home-dir=HOME-DIR`
18+
: Path to the phpcq home directory (default: `$(CWD)/.phpcq`)
19+
20+
`--ignore-platform-reqs`
21+
: Ignore platform requirements (`php` & `ext-` packages).
22+
23+
`-x, --cache=CACHE`
24+
: Path to the phpcq cache directory (default: `/$(HOME)/.cache/phpcq`)
25+
26+
`--channel=CHANNEL`
27+
: The channel of the release (default: `unstable`).
28+
29+
Right now only unstable is available.
30+
31+
`--base-uri=BASE-URI`
32+
: The base uri of the phpcq releases [default: "https://phpcq.github.io/distrib/phpcq"]
33+
34+
`--unsigned`
35+
: Disable signature checking
36+
37+
`--dry-run`
38+
: Do not perform update, only check for a new release.
39+
40+
`-f, --force`
41+
: Force to update

0 commit comments

Comments
 (0)