Review 13.4 Merged

92052[TASK] Live documentation for changelog and manuals

Garvin Hicking CR +2 V +2 Hard +289 −2 updated 12/09/25, 06:05

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
  • Verified V +2 Done
    • Garvin Hicking +2
    • core-ci +1 CI

Issues 1

Files 5

Review log 46

  1. Garvin Hicking commented on patch set 1 12/09/25, 05:42

    Cherry Picked from branch main.
  2. Garvin Hicking commented on patch set 2 12/09/25, 05:45

    Published edit on patch set 1.
  3. core-ci voted on patch set 1 V +1 12/09/25, 05:56 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/91856

  4. core-ci voted on patch set 2 V +1 12/09/25, 05:56 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/91859

  5. Garvin Hicking voted on patch set 2 CR +2 V +2 12/09/25, 06:05

  6. Garvin Hicking merged patch set 3 12/09/25, 06:05