Validate code blocks #97
Conversation
|
Now as I can see the code it could be placed in DOCtor as a simple rule. Not sure you want to give it a try |
|
I saw that all syntax checks was missing from this project. Once this is merged I will start to verify code blocks in a smarter way. Ie, when we define PHP Config with the ConfigBuilders I want to make sure the methods exists etc. So I need to side-load a Symfony project (with the correct version) to make sure things are working. I can do the same with Yaml and XML config too. But this PR is a first step. Im not sure if this is a feature of |
|
Oh, I definitely think this does belong to DOCtor more than this library (let's keep this library focused at building all the docs in symfony.com's infrastructure, that's already a pretty big task for 1 library). However, I think the Doctrine rst parser library opens up a whole new world for DOCtor. As Doctrine takes care of all the parsing, DOCtor can be more powerful (by creating event listeners on specific nodes, instead of first trying to make sense of plain text rst and then reviewing it). This PR proves how "easy" it is to create new check rules (thanks @Nyholm!). This completely bypasses my previous attempts on this topic (OskarStark/doctor-rst#719). |
While discussing to try out the Doctrine rst parser back in 2019, we also talked about this (smarter code checking, and even generation). Maybe we can learn from Fabien's way of building the book and also have some sort of "auto playable" code examples. In any case, I think it's a bit of a big topic to just start now to be honest. I would love to see all code examples to be updated to ConfigBuilders when 5.3.0 is released, and having this complex lexer first will make this near impossible I think. |
|
I just started looking into this library and DOCtor. As currently see it, it PR would be really hard to do without @OskarStark, do you see that we can fit in this into DOCtor? I was looking at some of the existing rules and they all work with plain texts, line by line. The alternative is to create a new "Code block verifier" project. That means a new CI job in symfony/symfony-docs.
Im unavailable tomorrow, but I'll can fix the parsers and a "baseline feature" on Sunday. ;) |
|
Im closing this PR. I added a small tool here: https://github.com/symfony-docs-tools/code-block-checker See this PR: symfony/symfony-docs#15257 |
This PR was squashed before being merged into the 4.4 branch. Discussion ---------- Fixing syntax error in PHP, XML and Yaml examples I used my new and shiny feature to the docs-parser =) https://github.com/weaverryan/docs-builder/pull/97 Commits ------- baf9154 Fixing syntax error in PHP, XML and Yaml examples
This PR was squashed before being merged into the 4.4 branch. Discussion ---------- Verify code blocks This PR is a first step to make sure we are using valid code blocks. I created a [small parser](https://github.com/symfony-docs-tools/code-block-checker) that will replace [the PR to the docs builder](https://github.com/weaverryan/docs-builder/pull/97). This CI job will look at the modified files, and give the the the [code-block-checker](https://github.com/symfony-docs-tools/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. Commits ------- c92641d Verify code blocks
Make sure that all our code examples are using valid syntax. I found quite a few things that should be updated.
This PR does not do any style checks, it just makes sure things can be parsed.
Note that validating the PHP examples are significantly slower. To build symfony docs takes 164s compared to 23s before this patch. Im sure there are optimisations and caching one can do. But I just wanted to share the performance impact.