feat(ci): implement automated syntax and static analysers for code samples in docs

[SamMousa]

This implements what was discussed in #11494.

It works roughly as follows:

1. Iterate over all .rst files in the docs/ folder.
2. For each of them look for a string containing whitespace and <?php.
3. Extract the block by looking for the indentation from 2 to end.
4. Check the content of each block against a list of ignored md5 hashes (think if this as a baseline for blocks that are too broken for PHPStan to be able to ignore them).
5. Write each block to a file.
6. Analyse the written files using PHPStan.

Locally you can improve existing blocks by looking for issues in the baseline. Alternatively you can edit the docs/extract.php and remove hashes from the $badBlocks array, this will lead to new errors for you to solve.
Extract blocks locally by doing php docs/extract.php docs/extracted_blocks.
Then run vendor/bin/phpstan -b phpstan-docs.neon.

Of course, before executing anything locally, read the source of docs/extract.php.

[SamMousa]

I guess this requires a bit more massaging:

• The docs contain a lot of examples that define classes without a namespace. These classes will collide, causing errors in analysis.
• We need to properly decide how we built up examples incrementally in docs.

Incremental examples

When looking at the getting started guide, an implementation of a Bug class is iterated over and extended several times. This is an issue for automatic analysis since we never have a proper full implementation of the Bug class.

One solution that is simple is to always number classes and reference the version explicitly. So we know if we're using Bug3. We then also need to make sure that we properly repeat code instead of using shorthands like:

    class Bug
    {
        // ... (previous code)

This is something I cannot decide on my own being new to the project. I'd love to hear what you think on how to standardize code samples that get iterated over in guides.

[greg0ire]

I think we should:

1. Migrate doctrine/doctrine-website to phpDocumentor/guides rather than doctrine/rst-parser, which does not support literalinclude, at least not in a version that is released
2. Migrate our docs to literalinclude

It should be way more robust.

If you want to help with that, please join us at https://app.slack.com/client/TA33F5Y6L/CERGRHPGD

[greg0ire]

@SamMousa hi! The migration is over, and I'm starting to experiment with literalinclude to see if it really works for us: #11667

[github-actions]

There hasn't been any activity on this pull request in the past 90 days, so it has been marked as stale and it will be closed automatically if no further activity occurs in the next 7 days.
If you want to continue working on it, please leave a comment.

[github-actions]

This pull request was closed due to inactivity.