#90806Create scripts to check for formatting errors in .rst files (e.g. for Changelog)
Description
Currently, there are no automatic checks to check for formatting errors in changelog.
- There are some checks though that check if the changelog complies to changelog conventions: Build/Scripts/validateRstFiles.php
- when building the docs, a Documentation-GENERATED-temp/Result/project/0.0.0/_buildinfo/warnings.txt is created, but this does not include some formatting errors which go undetected. However, it will report some problems.
- there may be other 3rdparty tools available I am not aware of.
Possibly an additional script could be added to check the changelogs for formatting problems.
Apparently, the best practice is using PHP scripts, see Build/Scripts/validateRstFiles.php or ask on Slack.
Problems with lists
Common problem is missing newline before the list. This will not get rendered correctly, see https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CommonPitfalls/Lists.html
You can easily find these with the following command:
cd typo3/sysext/core/Documentation
grep -r -B 1 -E "^(\*|\-) " . | grep "rst-" | grep -v -E "rst-(\*|$| )"
grep -r -A 1 -E "^(\*|\-) " . | grep "rst-" | grep -v -E "rst-(\*|$| )"
More …
Indenting
An additional problem (that manifests itself since the new theme) is a problem with unnecessary indenting. This is currently not mentioned (yet) in the “Common Pitfalls” chapter.
If you indent where it is not necessary, the block will be rendered as a quote (which is not what you want in most cases unless you really are using a quote), see https://typo3.slack.com/archives/C028JEPJL/p1586958179204000
Reviews 0
No change resolves or names this issue in its commit message, and no comment links one.
History 10
-
Sybille Peters commented 04/14/20, 11:36
-
Sybille Peters changed subject
Create scripts to check for formatting errors in .rst files in ChangelogCreate scripts to check for formatting errors in .rst files (e.g. for Changelog) 04/17/20, 10:20 -
Sybille Peters changed description 04/17/20, 10:27
-
Daniel Siepmann commented 04/22/20, 07:29
Mozilla is also using RST and validates syntax issues via rstcheck (https://github.com/myint/rstcheck).
Full list of their tools: https://firefox-source-docs.mozilla.org/code-quality/.
-
Lina Wolf changed status
NewAccepted assigned to Lina Wolf 03/19/22, 08:19 -
Lina Wolf commented and changed TYPO3 Version
1012 03/19/22, 08:20tried out dr. rst but didn’t get far yet: https://github.com/OskarStark/doctor-rst/issues/1120
-
Christian Kuhn commented and changed status
AcceptedNeeds Feedback 01/06/23, 12:05Hey.
I guess, checking details in the .rst files automatically before rendering will never be complete.
Our best bet is to occassionally check the rendering warning files instead.
We could still add some checks if this is really necessary, but especially the changelog files tend to be streamlined during the release process pretty well lately and issues are usually fixed. It may just not be worth the effort to check much more beforehand to the maintain the scripts.
Do you still think we should continue here? -
Sybille Peters commented 01/06/23, 13:09
From my end, we can close this. Unless Lina wants to start on this, she can reopen.
What was the most problematic in the past that there were actual rendering errors so the rendered changelogs were not updated and this was not noticed until several day later. But a better solution for that is a notification if rendering fails, I think (which might even be in place by now).
-
Christian Kuhn commented 12/18/23, 12:46
Thanks for feedback. Let’s close for now.
-
Christian Kuhn changed status
Needs FeedbackClosed 12/18/23, 12:46
About linting .rst, see Twitter:
> In case it’s useful for your project, our friend @OskarStark developed a linter for RST docs. It works great for Symfony Docs finding common issues and problems. It’s open source:
https://twitter.com/symfonydocs/status/1245641093598687232
The source: https://github.com/OskarStark/doctor-rst