Task #90806

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

Added by Sybille Peters 7 months ago. Updated 6 months ago.

Status:
New
Priority:
Should have
Assignee:
-
Category:
Documentation
Target version:
-
Start date:
2020-03-22
Due date:
% Done:

0%

TYPO3 Version:
10
PHP Version:
Tags:
Complexity:
Sprint Focus:

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

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

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

History

#1 Updated by Sybille Peters 6 months 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:

https://twitter.com/symfonydocs/status/1245641093598687232

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

#2 Updated by Sybille Peters 6 months 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)

#3 Updated by Sybille Peters 6 months ago

  • Description updated (diff)

#4 Updated by Daniel Siepmann 6 months 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