Verify code blocks #15257
Verify code blocks #15257
Conversation
|
Note that it will not complain about the existing syntax error (missing semi colon) in the cache.rst. (It will be fixed here). This is thanks to the baseline feature. |
|
The PR is updated. The docs team has an invitation to https://github.com/symfony-docs-tools |
|
Here is an example output that shows both a syntax error and where a code block for config will cause an issue on
|
There was a problem hiding this comment.
I'm not a super fan of automated code validations ... because sometimes in docs we might want to show some code which is technically wrong (e.g. a method outside of a class) but we do that consciously because it makes sense in that context.
But, I know we've talked about this for some time inside the Docs Team, so I think we should give this a try in practice. That's why I'm voting in favor of it. Thanks Tobias!
This PR was squashed before being merged into the 4.4 branch. Discussion ---------- Fixed syntax errors on 4.4 I ran the [new parser](#15257) on 4.4. There are about 130 more syntax errors that I decided not to fix. Some are false positives (ie a code example where we only have a PHP array). Others show some limitations of the parser. Ie, we cannot automatically detect a code block with no language, we currently assume it is PHP but that is not always correct. This is the last fixes I'll do for 4.4. Commits ------- 2a9103c Fixed syntax errors on 4.4
42a5814 to
c92641d
Compare
|
This is now merged! Thanks. |
|
Wohoo. It's going to be exiting to see how this works. |
This PR is a first step to make sure we are using valid code blocks. I created a small parser that will replace the PR to the docs builder.
This CI job will look at the modified files, and give the the the code-block-checker. That project will find the code blocks and make sure they are using valid syntax. It also supports a baseline so we can write invalid syntax if we want to. (it may sometimes make the examples more readable See #15250)
The next step is to make sure one can actually run code examples. Im planning to get all examples that starts with a comment and figure out if that is a filepath to the config directory. I will then capture any symfony errors when using that config.This is super helpful when updating the PHP config to use the config builders.EDIT: I included "the next step" in this PR. We do run all config examples.
Note that thanks to the baseline feature, will only report new errors on modified code blocks.