Review main Abandoned

86180[DOCS] Unify ReST syntax indentation at 4 spaces in changelogs

Garvin Hicking CR 0 V 0 Impossible +16237 −16219 updated 11/20/24, 12:16

Commit message

ReST syntax is relaxed in terms of required space indentation
before directives.

However, the documentation best-practice is to use 4 spaces.

This patch will aply that best practice to other changelogs.

This is an automated change by applying theis regular
expressions to every ReST document:

```
find . \
  -type f \
  -name "*.rst" \
  -exec sed -i '' -E 's/^\.\. ([^ ])/\.\.  \1/' {} +
```

This adapts every usage of a ".. [directive]"
syntax (for example: "..  index::" or "..  include::"
or "..  _some-index::") to use two spaces after the
dots, instead of only one.

The helper script validateRstFiles.php has been adapted
to enforce this 4-space variant.

Note that the 4-space indentation is also meant to be
used for lists, but due to their multi-line use,
it cannot be fixed/analyzed with a regular expression
properly.

Example:

```
* This is an old style list
  It uses two spaces.
  And multilines.

- Another variant of a list.
```

should better be:

```
*   This is a new style list
    It uses four spaces.
    And multilines.

-   Another variant of a list.
```

Since a regular expression would need to match "*" or "-" on the line,
and then also adopt every line after that, but stop when it hits two
newlines, this cannot be achieved without a safe, proper parser
and much work.

So for now we'll reap the low-hanging fruits and only
adjust the "..  directive" syntax.

Review

  • Code review CR 0
  • Verified V 0

Issues 1

Files 3684

Show 3664 more files

Review log 1418

  1. Garvin Hicking uploaded patch set 1 09/18/24, 12:27

  2. Garvin Hicking commented on patch set 1 09/18/24, 12:37

    I leave this up for discussion. It's painful to review. Will also be painful to backport. It's much more discrepance than I anticipated, so personally....I'd let this one go, and accept the fault-tolerance of the ReST parser to do "its thing".
  3. core-ci voted on patch set 1 V -1 09/18/24, 12:50 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/66133

  4. Garvin Hicking uploaded patch set 2 V -1 09/18/24, 13:18

    oh gawd
  5. core-ci voted on patch set 2 V +1 09/18/24, 13:39 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/66138

  6. Lina Wolf commented on patch set 2 CR -1 09/19/24, 13:46

    We descided to not make these kind of mass changes when we decided to switch from 3 spaces to 4 spaces. I can see no advantage whatover in this. You would have to make sure that you don't break rendering, for example the start is not the only sign that can be used for lists. There is really no advantage in applying mass-changes based on regexes without understanding the syntax. Also there is no need whatover to backport this as past changelogs are not being rendered and these are no content changes that would be useful for the TYPO3 backend. If at all I would apply the changes only to the Index.rst files to prevent future copy & paste.
  7. Benjamin Franzke commented on patch set 2 09/19/24, 14:51

    Reply

    motivation for such a change: https://review.typo3.org/c/Packages/TYPO3.CMS/+/86116/3#message-59c9cb76c6de982725dfd3fd942f876ac1e8426e There seem to be inconsistencies introduced also in new code, due to copy&pasting. Can't we "simply" check if the rendering is correct by rendering in pre-state and post-state, the HTML output should be equal, right?
  8. Lina Wolf commented on patch set 2 09/19/24, 15:00

    Such changes will also be futile unless https://forger.typo3.com/utilities/rst is changed
  9. Lina Wolf commented on patch set 2 CR 0 09/20/24, 06:03

    I will not block this even though I think it would be better to wait for a propper cgl tool for rst and then one and for all change all rst files. Needs to be souroughly tested though as it might break list, tables etc
  10. Garvin Hicking commented on patch set 2 09/20/24, 06:48

    Reply

    This is a good idea. I just rendered the whole docs and then diffed it after the patch was applied. There is no difference in the output. I had to ignore two occurences of differences: The "last rendered time" (which is in every file) and the "last rendered" meta tags (also in every file). So at least we can safely say this patch does not change the rendering output in any way. I agree if this gets merged we should adapt the ReST Utility, that shouldn't be too hard I hope. I'll get in touch with Andi about it.
  11. Benjamin Franzke commented on patch set 2 09/23/24, 06:36

    Reply

    ack, 4 spaces is now rolled out on https://forger.typo3.com/utilities/rst
    Hm? Do I get this wrong? The script should be adapted to only support 4 space indent and fail on 3 (at least in CI).

    Breaking-29342-ImproveValidatorTask.rst:24

    sidenode: wow, the 4space syntax feels really awkward for lists – but I guess you have discussed this a dozen times already.
  12. Garvin Hicking commented on patch set 2 09/23/24, 07:05

    Reply

    That would mean to comb through all older changelogs too, else the CI wouldn't let those files pass. That would make this patch pretty huge, but I can execute the regexps there too of course. We will then also do all of the Documentation files.

    Breaking-29342-ImproveValidatorTask.rst:24 Reply

    It predates my involvement ;-)
  13. Garvin Hicking uploaded patch set 3 V +1 10/15/24, 18:20

  14. Garvin Hicking commented on patch set 3 10/15/24, 18:26

    Reply

    Done. Please see the notes in the commit message, this has a caveat.
  15. core-ci voted on patch set 3 V +1 10/15/24, 18:26 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/67848

  16. Oliver Hader updated the commit message in patch set 4 V +1 10/18/24, 13:55

  17. core-ci voted on patch set 4 V +1 10/18/24, 19:32 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/68085

  18. Garvin Hicking abandoned the change 11/20/24, 12:16

    I believe there is no good way to enforce this in the CI/workflow. True benefit is low, and possible impact to annoy people too high.