Review main Merged

91581[TASK] Live documentation for changelog and manuals

Garvin Hicking CR +2 V +2 Hard +289 −2 updated 11/15/25, 09:18

Commit message

This is a Developer/Contributor "quality of life" patch.

Creating ReST documentation is a tedious effort at times.
If you do not often work with ReST syntax, it's hard
to create an initial file, iteratively work on it, spot
syntax mistakes and "beautify" your content.

The docker-based rendering process made that a bit
more easy, but it required you to run the docker command
on your own (probably with a shell alias), for example
the changelogs:

> docker run --rm --pull always -v ./:/project/ \
    ghcr.io/typo3-documentation/render-guides:latest \
    --config=typo3/sysext/core/Documentation \
    typo3/sysext/core/Documentation

After that, you had to locally open the HTML files
in `typo3/sysext/core/Documentation/Changelog/Index.html`.

And after each change, you had to redo the process.
Rendering changelogs was a process of a few minutes.

This has now changed with the `render-guides:0.35` release.

The documentation container now supports "Live Documentation",
see: https://typo3.org/article/introducing-live-documentation-preview

This means, a local webserver is started once, and allows
you to do editing of the file next to a browser, and every
change to the `.rst` file reloads the browser to directly
show you the result.

To make this process even easier, running this process
is now added to our `runTests.sh` dispatcher.

It directly spawns the webserver and can render a distinct
manual or the changelogs:

> ./Build/Scripts/runTests.sh -s watchRst seo
> ./Build/Scripts/runTests.sh -s watchRst core

A bonus goodie is added for changelog entries, the dispatcher
can actually create boilerplate ReST files for a Feature,
Breaking, Important and Deprecation format - like the
good old https://forger.typo3.com/utilities/rst does, but
without any copy+paste effort:

> ./Build/Scripts/runTests.sh -s watchRst core \
    Changelog/14.0/Breaking-999999-FileIsMissing.rst

This would automatically create a "Breaking" type ReST file,
and insert issue number and issue title inside of it,
ready to be committed. If a file exists, it will not be
overwritten - and the command output will directly
give you the localhost URL to see the result.

On top of that, a new file can be created interactively:

> ./Build/Scripts/runTests.sh -s watchRst core interactive

The rendering runs on port 1337 by default. You can map
any other port with a third command:

> ./Build/Scripts/runTests.sh -s watchRst core interactive 4711

The interactive process will directly know the current
GIT branch of the TYPO3 repository, and put the file in the
"current" subdirectory (14.0, 14.1, ...).

Review

  • Code review CR +2 Done
    • Garvin Hicking +2
    • Josef Glatz +1
    • Anja Leichsenring +1
    • Helmut Hummel +1
  • Verified V +2 Done
    • Garvin Hicking +2
    • Josef Glatz +1
    • Anja Leichsenring +1
    • Helmut Hummel +1
    • core-ci +1 CI

Issues 1

Files 5

Review log 1215

  1. Garvin Hicking uploaded patch set 1 11/12/25, 12:52

  2. core-ci voted on patch set 1 V -1 11/12/25, 13:01 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/89312

  3. Garvin Hicking uploaded patch set 2 V -1 11/12/25, 20:14

  4. core-ci voted on patch set 2 V -1 11/12/25, 20:22 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/89395

  5. Josef Glatz commented on patch set 2 11/13/25, 05:30

    just reading the commit of this lovely features: the command for "creating a new file" is `-s watchRst`? Would it be better to add an additional self-explanatory named command for creating (even if it starts watching) like `createRst`?
  6. Garvin Hicking commented on patch set 2 11/13/25, 07:30

    Reply

    We have very many parameters for "-s" - I do not want to create more than one command, and bundle it for the "watch" scope for now... also so you dont have to run two commands but just one in the workflow.
  7. Josef Glatz commented on patch set 2 11/13/25, 08:24

    Reply

    ACK
  8. Garvin Hicking rebased onto patch set 3 V -1 11/13/25, 08:47

  9. core-ci voted on patch set 3 V +1 11/13/25, 08:57 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/89440

  10. Helmut Hummel commented on patch set 3 CR +1 V +1 11/14/25, 10:49

    I love it!
  11. Josef Glatz voted on patch set 3 V +1 11/14/25, 11:17

  12. Josef Glatz voted on patch set 3 CR +1 11/14/25, 12:54

  13. Anja Leichsenring voted on patch set 3 CR +1 V +1 11/15/25, 09:07

  14. Garvin Hicking commented on patch set 3 CR +2 V +2 11/15/25, 09:18

    Reply

    Much appreciated :) I hope that'll help people!
  15. Garvin Hicking merged patch set 4 11/15/25, 09:18