Task #90806

Create scripts to check for formatting errors in .rst files (e.g. for Changelog)

Added by Sybille Peters over 1 year ago. Updated about 1 year ago.

Should have
Target version:
Start date:
Due date:
% Done:


Estimated time:
TYPO3 Version:
PHP Version:
Sprint Focus:


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 ...

see https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CommonPitfalls/Index.html


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


Updated by Sybille Peters about 1 year ago

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:


The source: https://github.com/OskarStark/doctor-rst


Updated by Sybille Peters about 1 year ago

  • Subject changed from Create scripts to check for formatting errors in .rst files in Changelog to Create scripts to check for formatting errors in .rst files (e.g. for Changelog)

Updated by Sybille Peters about 1 year ago

  • Description updated (diff)

Updated by Daniel Siepmann about 1 year ago

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/.

Also available in: Atom PDF