feat(Linter/DocString): ignore Verso linter errors about links and LaTeX#37588
Open
Vierkantor wants to merge 1 commit intoleanprover-community:masterfrom
Open
feat(Linter/DocString): ignore Verso linter errors about links and LaTeX#37588Vierkantor wants to merge 1 commit intoleanprover-community:masterfrom
Vierkantor wants to merge 1 commit intoleanprover-community:masterfrom
Conversation
I went through [the weekly linting log](https://leanprover.zulipchat.com/#narrow/channel/287929-mathlib4/topic/Weekly.20linting.20log/near/582485221) and found most of the warnings come from three sources. All of these are sensical syntax in our current Markdown dialect, and should be fixed automatically by a script, instead of manually. I expect after these changes we'll be down to hundreds of linter errors rather than two thousand. * References [between square brackets] without a following link URL. Verso has different implementations for references depending on what kind they are, and since there are a thousand references we should be using a script to fix these. * Autolinks: bare URLs or URLs between <pointy brackets>. Autolinks are intentionally not supported by Verso but replacing every `https://...` with `[https://...](https://...)` would be too noisy. * LaTeX blocks: Verso does have TeX blocks but with an incompatible syntax. Better to fix it with a script. I ended up using preprocessing in addition to postprocessing to filter out errors: using the error message we can determine whether it is a reference, but for errors caused by autolinks and LaTeX blocks I couldn't figure out how to do so easily: the information about the parse error does report a string position but this is always the last character of the docstring. So instead we modify the docstring before it is passed into Verso to get rid of the offending syntax.
PR summary 551ca8f603Import changes exceeding 2%
|
| File | Base Count | Head Count | Change |
|---|---|---|---|
| Mathlib.Tactic.Linter.DocString | 1 | 2 | +1 (+100.00%) |
Import changes for all files
| Files | Import difference |
|---|---|
| There are 7829 files with changed transitive imports taking up over 339393 characters: this is too many to display! | |
You can run ci-tools/scripts/pr_summary/import_trans_difference.sh all locally to see the whole output. |
Declarations diff
+ isSilencedVersoWarning
+ lintVersoSyntax
You can run this locally as follows
## summary with just the declaration names:
./scripts/pr_summary/declarations_diff.sh <optional_commit>
## more verbose report:
./scripts/pr_summary/declarations_diff.sh long <optional_commit>The doc-module for scripts/pr_summary/declarations_diff.sh contains some details about this script.
No changes to technical debt.
You can run this locally as
./scripts/reporting/technical-debt-metrics.sh pr_summary
- The
relativevalue is the weighted sum of the differences with weight given by the inverse of the current value of the statistic. - The
absolutevalue is therelativevalue divided by the total sum of the inverses of the current values (i.e. the weighted average of the differences).
Vierkantor
added a commit
to Vierkantor/mathlib4
that referenced
this pull request
Apr 3, 2026
This PR goes through the first few errors in the docstring Verso linter that haven't been silenced by leanprover-community#37588 and fixes the issues that got flagged. It is not a systematic cleanup, just things spotted while I was debugging the linter.
mathlib-bors bot
pushed a commit
that referenced
this pull request
Apr 3, 2026
This PR goes through the first few errors in the docstring Verso linter that haven't been silenced by #37588 and fixes the issues that got flagged. It is not a systematic cleanup, just things spotted while I was debugging the linter. Co-authored-by: Anne C.A. Baanen <vierkantor@vierkantor.com>
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.
I went through the weekly linting log and found most of the warnings come from three sources. All of these are sensical syntax in our current Markdown dialect, and should be fixed automatically by a script, instead of manually. I expect after these changes we'll be down to hundreds of linter errors rather than two thousand.
https://...with[https://...](https://...)would be too noisy.I ended up using preprocessing in addition to postprocessing to filter out errors: using the error message we can determine whether it is a reference, but for errors caused by autolinks and LaTeX blocks I couldn't figure out how to do so easily: the information about the parse error does report a string position but this is always the last character of the docstring. So instead we modify the docstring before it is passed into Verso to get rid of the offending syntax.