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