Project

General

Profile

Actions

Task #90806

closed

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

Added by Sybille Peters almost 4 years ago. Updated 3 months ago.

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

0%

Estimated time:
TYPO3 Version:
12
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

Actions #1

Updated by Sybille Peters almost 4 years 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

Actions #2

Updated by Sybille Peters almost 4 years 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)
Actions #3

Updated by Sybille Peters almost 4 years ago

  • Description updated (diff)
Actions #4

Updated by Daniel Siepmann almost 4 years 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/.

Actions #5

Updated by Lina Wolf about 2 years ago

  • Status changed from New to Accepted
  • Assignee set to Lina Wolf
Actions #6

Updated by Lina Wolf about 2 years ago

  • TYPO3 Version changed from 10 to 12

tried out dr. rst but didn't get far yet: https://github.com/OskarStark/doctor-rst/issues/1120

Actions #7

Updated by Christian Kuhn about 1 year ago

  • Status changed from Accepted to Needs Feedback

Hey.

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?

Actions #8

Updated by Sybille Peters about 1 year ago

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

Actions #9

Updated by Christian Kuhn 3 months ago

Thanks for feedback. Let's close for now.

Actions #10

Updated by Christian Kuhn 3 months ago

  • Status changed from Needs Feedback to Closed
Actions

Also available in: Atom PDF