doc: Fix various linted errors (#1224)

Author: theofidry

.github/workflows/docs-empty.yaml

@@ -4,10 +4,10 @@ name: Null Docs
 on:
     # To be aware it need to be the counter-part of docs.yaml.
     pull_request:
-        paths-ignore:
-            - doc/**
-            - mkdocs.yaml
-            - .github/workflows/docs.yaml
+        paths:
+            - '!doc/**'
+            - '!mkdocs.yaml'
+            - '!.github/workflows/docs.yaml'
 
 # See https://stackoverflow.com/a/72408109
 concurrency:

.github/workflows/docs.yaml

@@ -35,7 +35,7 @@ jobs:
             -   name: Check Markdown formatting
                 uses: DavidAnson/markdownlint-cli2-action@v13.0.0
                 with:
-                    globs: "*.md|docs/**/*.md"
+                    globs: "*.md|doc/**/*.md"
 
     check-links:
         name: Lint Links
@@ -56,7 +56,7 @@ jobs:
                 uses: lycheeverse/lychee-action@v1.8.0
                 with:
                     # To keep in sync with Makefile#lychee
-                    args: "--verbose --no-progress '*.md' 'docs/**/*.md' --cache --max-cache-age 1d ."
+                    args: "--verbose --no-progress '*.md' 'doc/**/*.md' --cache --max-cache-age 1d ."
                     output: ${{ runner.temp }}/lychee/out.md
                     fail: true
 

.markdownlint.jsonc

@@ -7,4 +7,6 @@
     "MD033": false,
     "MD034": false,
     "MD041": false,
+    "MD046": false,
+    "MD053": false,
 }

Makefile

@@ -327,7 +327,7 @@ website_check: markdownlint lychee website_build
 markdownlint:
 	@echo "$(YELLOW_COLOR)Ensure you have the nodejs & npm installed. For more information, check:$(NO_COLOR)"
 	@# To keep in sync with .github/workflows/gh-pages.yaml#check-links
-	npx markdownlint-cli2 "*.md|docs/**/*.md"
+	npx markdownlint-cli2 "*.md|doc/**/*.md"
 
 .PHONY: lychee
 lychee:

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-    <img src="doc/img/box.png" width=900 />
+    <img src="doc/img/box.png" width=900 alt="Box logo" />
 </p>
 
 

doc/code-isolation.md

@@ -7,7 +7,7 @@
 
 ## Why/Explanation
 
-When bundling the code in a PHAR, it is equivalent to compacting all the code in a single file. However unlike in a 
+When bundling the code in a PHAR, it is equivalent to compacting all the code in a single file. However unlike in a
 compiled language, the code does not change. This, when the PHAR _loads_ external code, can lead to dependency
 conflicts.
 
@@ -22,7 +22,7 @@ myapp.phar myscript.php
 For the sake of the example, `myapp.phar` is using Composer and loads the YAML component right away when starting, i.e.
 when running `myapp.phar`, the class `Symfony\Yaml\Yaml` _from the PHAR_ is going to be loaded. Now what `myapp.phar`
 is actually going to do is scan the whole file given, and do some reflection work on each classes found. I.e. for each
-class `$class` found, it will do `new \ReflectionClass($class)`. 
+class `$class` found, it will do `new \ReflectionClass($class)`.
 
 Now if `myscript.php` is using the Symfony YAML 4.0.0 component with some new features added in 4.0.0 that are
 non-existent in 2.8.0, when doing `new \ReflectionClass('Symfony\Yaml\Yaml')`, the class `Symfony\Yaml\Yaml` will be
@@ -45,12 +45,12 @@ Box provides an integration with [PHP-Scoper][php-scoper]. To use it, [enable th
 compactor][php-scoper-compactor].
 
 If you need an extra configuration for PHP-Scoper, you can create a `scoper.inc.php` file as
-[per the documentation][php-scoper-config]. The only difference is that you can ignore the `finders` setting as the 
+[per the documentation][php-scoper-config]. The only difference is that you can ignore the `finders` setting as the
 files to scope are already collected by Box.
 
 And that's it!
 
-Warning: keep in mind however that scoping is a very brittle process due to the nature of PHP. As such you will likely 
+Warning: keep in mind however that scoping is a very brittle process due to the nature of PHP. As such you will likely
 need some adjustments in your code or the configuration.
 
 

doc/configuration.md

@@ -128,7 +128,7 @@ When the parameter is not given or set to `null`, Box tries to guess the binary
 `composer.json` file. If the [Composer `bin`][composer-bin] is set, Box will pick the first value provided. Otherwise it
 will fallback on the [PHAR][phar class] default file used which is `index.php`.
 
-The main file contents is processed by the [compactors][compactors] as the other files. 
+The main file contents is processed by the [compactors][compactors] as the other files.
 
 If the main file starts with a shebang line (`#!`), it will be automatically removed (the shebang line goes in the
 [stub][stub] for a PHAR and is configured by the [shebang][shebang] setting).
@@ -158,9 +158,9 @@ constraint before running. See more information about it [here][requirement-chec
 the requirement checker will be added. Note that this is true only if either the `composer.json`  or `composer.lock`
 could have been found.
 
-!!! Warning 
+!!! Warning
     this check is still done within the PHAR. As a result, if [the required extension to open the PHAR][compression]
-    due to the compression algorithm is not loaded, a hard failure will still appear: the requirement 
+    due to the compression algorithm is not loaded, a hard failure will still appear: the requirement
     checker _cannot_ be executed before that.
 
 
@@ -196,7 +196,7 @@ The `force-autodiscovery` (`bool` default `false`) setting forces Box to attempt
 though you are using the [`directories`][directories] or [`finder`][finder] setting.
 
 When Box tries to find which files to include, it may remove some files such as readmes or test files. If however you
-are using the [`directories`][directories] or [`finder`][finder], Box will _append_ the found files to the ones you 
+are using the [`directories`][directories] or [`finder`][finder], Box will _append_ the found files to the ones you
 listed.
 
 
@@ -228,7 +228,7 @@ Files listed in the [`blacklist`][blacklist] will not be added to the PHAR.
 the files such as images, those that contain binary data or simply a file you do not want to alter at all despite using
 compactors.
 
-!!! Warning 
+!!! Warning
     Setting the key `directories` (regardless of its value), will disable the file auto-discovery. If you want
     to keep it, check the [force the auto-discovery][force-autodiscovery] setting.
 
@@ -243,7 +243,7 @@ compactors.
     included in `directories` (respectively `directories-bin`), the those files **will be included**. The files included
     are a union of the directives.
 
-!!! Warning 
+!!! Warning
     Symlinks are not followed/supported.
 
 
@@ -252,7 +252,7 @@ compactors.
 The finder (`object[]`|`null` default `[]`) setting is a list of JSON objects. Each object (key, value) tuple is a
 (method, arguments) of the [Symfony Finder][symfony-finder] used by Box. If an array of values is provided for a single
 key, the method will be called once per value in the array.
- 
+
 Note that the paths specified for the `in` method are relative to [`base-path`][base-path] and that the finder will
 account for the files registered in the [`blacklist`][blacklist].
 
@@ -307,7 +307,7 @@ blacklisted are the ones found using the other available configuration settings:
 Note that all the blacklisted paths are relative to the settings configured above. For example if you have the following
 file structure:
 
-```
+```text
 project/
 ├── box.json.dist
 ├── A/
@@ -335,7 +335,7 @@ With:
 Box will try to collect all the files found in `project` (cf. [Including files][including-files]) but will exclude `A/`
 and `B/A resulting in the following files being collected:
 
-```
+```text
 project/
 ├── box.json.dist
 └── B/
@@ -372,14 +372,15 @@ belonging to dev only packages. For example for the given project:
     }
 }
 ```
+
 </details>
 
 The `vendor` directory will have `beberlei/assert` and `bamarni/composer-bin-plugin`. If `exclude-dev-files` is not
 disabled, the `bamarni/composer-bin-plugin` package will be removed from the PHAR.
 
 This setting will automatically be disabled when [`dump-autoload`][dump-autoload] is disabled. Indeed, otherwise some
-files will not be shipped in the PHAR but may still appear in the Composer autoload classmap, resulting in an 
-autoloading error. 
+files will not be shipped in the PHAR but may still appear in the Composer autoload classmap, resulting in an
+autoloading error.
 
 
 ### Map (`map`)
@@ -420,13 +421,14 @@ the above files will be stored with the following paths in the PHAR:
 The [PHAR stub][phar.fileformat.stub] file is the PHAR bootstrapping file, i.e. the very first file executed whenever
 the PHAR is executed. It usually contains things like the PHAR configuration and executing the [main script file][main].
 
-The default PHAR stub file can be used but Box also propose a couple of options to customize the stub used. 
+The default PHAR stub file can be used but Box also propose a couple of options to customize the stub used.
 
 
 ### Stub (`stub`)
 
 The stub (`string`|`boolean`|`null` default `true`) setting is used to specify the location of a stub file or if one
 should be generated:
+
 - `string`: Path to the stub file will be used as is inside the PHAR
 - `true` (default): A new stub will be generated
 - `false`: The default stub used by the PHAR class will be used
@@ -440,7 +442,7 @@ If a custom stub file is provided, none of the other options ([`shebang`][sheban
 The shebang (`string`|`false`|`null`) setting is used to specify the shebang line used when generating a new stub. By
 default, this line is used:
 
-```
+```sh
 #!/usr/bin/env php
 ```
 
@@ -543,7 +545,7 @@ done for you.
 
 For example `Custom banner` will result in the stub file:
 
-```
+```php
 /*
  * Custom banner
  */
@@ -659,7 +661,7 @@ command ✨.
 ### Annotations (`annotations`)
 
 The annotations (`boolean`|`object`|`null` default `true`) setting is used to enable compacting annotations in PHP source
-code. 
+code.
 
 This setting is only taken into consideration if the [`KevinGH\Box\Compactor\Php` compactor][compactors] is enabled.
 
@@ -689,6 +691,7 @@ function foo($x, $y): int {
     return $x <=> $y;
 }
 ```
+
 </details>
 
 <details>
@@ -715,6 +718,7 @@ function foo($x, $y): int {
  return $x <=> $y;
 }
 ```
+
 </details>
 
 
@@ -786,7 +790,7 @@ available:
 
 By default, PHARs are `SHA1` signed.
 
-The `OPENSSL` algorithm will require to provide [a key][key]. 
+The `OPENSSL` algorithm will require to provide [a key][key].
 
 !!! warning
 
@@ -846,7 +850,7 @@ With the configuration excerpt:
 
 Then the `Phar::getMetadata()` will return `['application_version' => '1.0.0-dev']` array.
 
-!!! warning 
+!!! warning
 
     Your callable function must be readable by your autoloader.
 
@@ -1037,7 +1041,6 @@ The short commit hash will only be used if no tag is available.
 [git-commit-short]: #short-git-commit-placeholder-git-commit-short
 [git-tag-placeholder]: #git-tag-placeholder-git-tag
 [git-version-placeholder]: #git-version-placeholder-git-version
-[herrera-io/php-annotations]: https://github.com/herrera-io/php-annotations
 [including-files]: #including-files
 [intercept]: #intercept-intercept
 [key-pass]: #the-private-key-password-key-pass
@@ -1055,7 +1058,6 @@ The short commit hash will only be used if no tag is available.
 [phar.mapphar]: https://secure.php.net/manual/en/phar.mapphar.php
 [phar.setalias]: https://secure.php.net/manual/en/phar.setalias.php
 [phar.setsignaturealgorithm]: https://secure.php.net/manual/en/phar.setsignaturealgorithm.php
-[phar.webphar]: https://secure.php.net/manual/en/phar.webphar.php
 [php-date-format]: https://secure.php.net/manual/en/function.date.php
 [php-scoper-compactor]: #php-scoper-php-scoper
 [php-scoper-configuration]: https://github.com/humbug/php-scoper#configuration

doc/docker.md

@@ -3,19 +3,19 @@
 Besides generating a PHAR, you may want to create a [Docker][docker] image for your application. To do so, you can
 either:
 
-- Directly generate the `Dockerfile` when generating the PHAR with the `--with-docker` option of the Box `compile` 
+- Directly generate the `Dockerfile` when generating the PHAR with the `--with-docker` option of the Box `compile`
   command
 - Generate the `Dockerfile` for a given PHAR with the Box `docker` command
 
-The command will attempt to generate a `Dockerfile` for your PHAR, leveraging the 
-[requirement checker][requirement-checker]. Once the file generated, you have free hands on it: you can either use it 
+The command will attempt to generate a `Dockerfile` for your PHAR, leveraging the
+[requirement checker][requirement-checker]. Once the file generated, you have free hands on it: you can either use it
 right away (you just need to run `$ docker build .` to create the docker image) or you can tweak it however you want.
 
 In your `Dockerfile` (generated by Box), you should see the following line:
 
 ```Dockerfile
 RUN $(php -r '$extensionInstalled = array_map("strtolower", \get_loaded_extensions(false));$requiredExtensions = ["zlib", "phar", "openssl", "pcre", "tokenizer"];$extensionsToInstall = array_diff($requiredExtensions, $extensionInstalled);if ([] !== $extensionsToInstall) {echo \sprintf("docker-php-ext-install %s", implode(" ", $extensionsToInstall));}echo "echo \"No extensions\"";')
-``` 
+```
 
 This cryptic one-liner PHP script is about installing the required extensions for your application: it compares the ones
 your application requires with the ones already provided by the base PHP image, and then install them using the

doc/faq.md

@@ -127,7 +127,7 @@ See [Phar::running()][phar-running] for more information.
 If you need to include Box as part of your dependencies and include it within your PHAR, you will probably encounter
 the following issue when building your PHAR:
 
-```
+```text
 Could not dump the autoloader.
 [...]
 Could not scan for classes inside "/path/to/vendor/humbug/php-scoper/vendor-hotfix/" which does not appear to be a file nor a folder

doc/index.md

@@ -45,7 +45,7 @@ permissions:
 You can then find more advanced configuration settings in [the configuration documentation][configuration].
 For more information on which command or options is available, you can run:
 
-```
+```shell
 box help
 ```
 
@@ -73,7 +73,7 @@ The text displayed by the commands (e.g. `compile` or `info`) or the content of
 Project originally created by: [Kevin Herrera] ([@kherge]) which has now been moved under the [Humbug umbrella][humbug].
 
 
-[box2]: https://github.com/box-project/box2
+[configuration]: configuration.md
 [Kevin Herrera]: https://github.com/kherge
 [@kherge]: https://github.com/kherge
 [humbug]: https://github.com/humbug

doc/installation.md

@@ -102,4 +102,3 @@ docker pull boxproject/box
 [docker-image]: https://hub.docker.com/r/boxproject/box
 [bamarni/composer-bin-plugin]: https://github.com/bamarni/composer-bin-plugin
 [phive]: https://github.com/phar-io/phive
-[github-release]: https://github.com/box-project/box/releases

doc/phar-signing.md

@@ -113,7 +113,7 @@ gpg --gen-key
 It will ask for some questions. It is recommended to use a passphrase (ideally generated and managed by a reputable
 password manager). In the end, you will end up with something like this:
 
-```
+```shell
 # $ gpg --gen-key output
 pub   ed25519 2023-10-21 [SC] [expires: 2026-10-20]
       96C8013A3CC293C465EE3FBB03B2F4DF7A20DF08
@@ -145,7 +145,7 @@ gpg --keyserver keys.openpgp.org --send-key 96C8013A3CC293C465EE3FBB03B2F4DF7A20
 ```
 
 [^1]:
-    
+
     There is several OpenPGP Keyservers. It is recommended to push your keys to [keys.openpgp.org] _at least_, but you
     can also push it to other servers if you wish to.
 
@@ -156,7 +156,7 @@ revocation certificate to the keyserver to invalidate the signing key.
 gpg --output revoke-96C8013A3CC293C465EE3FBB03B2F4DF7A20DF08.asc --gen-revoke 96C8013A3CC293C465EE3FBB03B2F4DF7A20DF08
 ```
 
-This will leave you with a revocation certificate in the file `revoke-96C8013A3CC293C465EE3FBB03B2F4DF7A20DF08.asc` 
+This will leave you with a revocation certificate in the file `revoke-96C8013A3CC293C465EE3FBB03B2F4DF7A20DF08.asc`
 which can be added to your password manager.
 
 
@@ -185,7 +185,7 @@ gpg --export-secret-key --armor 96C8013A3CC293C465EE3FBB03B2F4DF7A20DF08 >> keys
 
 If your goal is to save this encryption key somewhere, for example your repository, you should first encrypt it:
 
-```
+```shell
 gpg --symmetric keys.asc
 ```
 
@@ -194,7 +194,7 @@ ideally one generated and managed by a password manager.
 
 This leaves you with a file `keys.asc.gpg`. You can add this one to the repository and at this point you are probably
 better off **deleting the `keys.asc` file**. In order to do the actual signing, you will have to decrypt it again, but
-it is better to not keep that decrypted key around. 
+it is better to not keep that decrypted key around.
 
 
 ### Sign your PHAR
@@ -240,7 +240,7 @@ When publishing your archive, you should publish both `bin/command.phar` and `bi
 First you should check the issuer's identity, usually it is provided from where you download it as part of the
 documentation:
 
-```
+```shell
 # If you are on the same machine as where you created the key, then this step is unnecessary.
 # You will need this however for when verifying a different key that you do not know of yet.
 gpg --keyserver hkps://keys.openpgp.org --recv-keys 96C8013A3CC293C465EE3FBB03B2F4DF7A20DF08