Setup GitHub actions to check documentation files#1603
Merged
henriquemoody merged 5 commits intoRespect:mainfrom Jan 15, 2026
Merged
Setup GitHub actions to check documentation files#1603henriquemoody merged 5 commits intoRespect:mainfrom
henriquemoody merged 5 commits intoRespect:mainfrom
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1603 +/- ##
=========================================
Coverage 97.46% 97.46%
Complexity 991 991
=========================================
Files 211 211
Lines 2292 2292
=========================================
Hits 2234 2234
Misses 58 58 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
henriquemoody
force-pushed
the
housekeeping/docs
branch
2 times, most recently
from
7a1aa61 to
d2ea08d
Compare
There was a problem hiding this comment.
Pull request overview
This pull request sets up GitHub Actions to automatically check documentation files and refactors the documentation generation system. The PR replaces a single monolithic UpdateDocLinksCommand with four specialized commands that each handle a specific aspect of documentation generation: validator headers, index, related validators, and templates. It also introduces new Markdown\Builder and Markdown\Differ classes to provide better tooling for generating and comparing markdown content.
Changes:
- Introduced new markdown generation infrastructure with
BuilderandDifferclasses - Replaced
UpdateDocLinksCommandwith four specialized commands for different documentation aspects - Added GitHub Actions workflow to validate documentation files on CI
- Updated numerous validator documentation files with corrected parameter names, type annotations, and formatting
Reviewed changes
Copilot reviewed 57 out of 58 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
| src-dev/Markdown/Differ.php | New class for generating colored diffs of markdown content |
| src-dev/Markdown/Builder.php | New class providing a fluent API for building markdown documents |
| src-dev/Commands/DocsValidatorsTemplatesCommand.php | New command to update validator template tables in documentation |
| src-dev/Commands/DocsValidatorsRelatedCommand.php | New command to update related validator links in documentation |
| src-dev/Commands/DocsValidatorsListCommand.php | New command to generate the index of validators by category |
| src-dev/Commands/DocsValidatorsHeadersCommand.php | New command to update validator function signatures in documentation |
| src-dev/Commands/UpdateDocLinksCommand.php | Removed old monolithic documentation update command |
| composer.json | Added sebastian/diff dependency and new composer scripts for documentation commands |
| bin/console | Updated to register new documentation commands with Differ dependency |
| docs/validators/*.md | Updated validator documentation with corrected signatures, parameter names, and formatting |
| docs/validators/index.md | Updated index page with new title and removed duplicate Type validator entries |
| docs/index.md | Updated link to new validators index location |
| docs/getting-started.md | Updated link to new validators index location |
| README.md | Updated link to new validators index location |
| .github/workflows/continuous-integration-docs.yml | New workflow to validate documentation files |
| .github/workflows/continuous-integration-code.yml | Renamed workflow title for clarity |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
henriquemoody
force-pushed
the
housekeeping/docs
branch
2 times, most recently
from
adf30b7 to
bb3be23
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 63 out of 64 changed files in this pull request and generated 16 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
henriquemoody
force-pushed
the
housekeeping/docs
branch
7 times, most recently
from
4031f12 to
d9b4053
Compare
When we make changes to the category of a validator, it's easy to forget to update overall list of validators. This commit a GitHub actions that will run a console command to check if the documentation it up-to-date. The job will fail when we need to change the document, but the console command will fix the issues, so there isn't a lot of friction there.
When we make changes to the code, renaming variables, or adding parameters to a validator, it's easy to forget to update the documentation. With this change, we avoid having a disparity between the documentation and the code.
This commit ensures that if validator A has a direct link to validator B, validator B will have a direct link to validator A too.
We don't often change the tempaltes of validators, but when we do it's extremely important that the documentation of the validators match the exact template the validator has.
There's more value on showing how `assert()` displays the validation messages than simply showing if `isValid()` returns `true` or `false`. However, that increases the chances of having outdated documentation, so I created a doc linter that updates the Markdown files with the correct message.
henriquemoody
force-pushed
the
housekeeping/docs
branch
from
d9b4053 to
d2198df
Compare
alganet
approved these changes
Jan 15, 2026
Member
alganet
left a comment
alganet
left a comment
There was a problem hiding this comment.
I like this.
Perhaps this one should be a separate component. Some kind of ValidationDocUtils kind of thing. I can imagine someone that does custom validators wanting to keep their docs in line with ours. However, that's an idea not for now, just to keep in the corner of the mind :)
Member
Author
|
That's a great idea! Perhaps something for 3.1, what do you say? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request configures GitHub actions to check flaws in the documentation. Many documents we have are related to actual code, and sometimes they get out of sync. By running this command in the workflow, we make sure that the changes we made will be reflected in the documentation files.