Docker¶

The Docker image is available on GitHub packages. You can pull the image with the following command.

docker pull ghcr.io/typo3-documentation/render-guides:latest

For all available tags, please check the GitHub packages page. Once you have pulled the image, you can run the image to render your project's documentation.

docker run --rm -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest --progress --config ./Documentation

Unlike other Docker images, this image will detect the owner-user of the mounted project. This means that the files created by the Docker image will have the same owner as the files in your project. No more permission issues should occur, when files are getting generated inside the image.

If this fail, you can resort to specifying the user:

docker run --rm --user=$(id -u):$(id -g) -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest --progress --config ./Documentation

The provided image allows you to also perform a few other actions:

# Convert Settings.cfg to guides.xml:
docker run --rm -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest migrate ./Documentation

# Check guides.xml files for XML conformity
docker run --rm -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest lint-guides-xml

# Adapt guides.xml programmatically (work in progress)
docker run --rm -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest configure \
  --project-version="2.2" \
  --project-title="My project title" \
  --project-release="2023" \
  --project-copyright="2000-2023" ./Documentation

In case of errors you can increase verbose output by prefixing any command with the argument verbose:

# Execute verbose commands with inline setting
docker run --rm -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest verbose (render|migrate|lint-guides-xml|configure) [arguments/options]

# Execute verbose commands with inline setting, useful for i.e. external actions
SHELL_VERBOSITY=3 docker run --rm -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest (render|migrate|lint-guides-xml|configure) [arguments/options]

Another way to utilize Docker is to create your own image/container. This is aimed at people who want to contribute to the underlying Documentation tool. Please see Building for those steps.

DDEV¶

DDEV is a utility layer on top of Docker. It allows to easily build and maintain local development instances with specific environments.

This project also ships a .ddev/ configuration directory, that allows you to start a specific container in which you can render Documentation, and have an environment where you can contribute to this repository without any other requirement than Docker and DDEV.

To render the documentation you can run

ddev start
ddev composer install
ddev composer make docs

PHP¶

If your host environment already has a PHP binary and is able to run Composer, as well as interpret Makefile syntax (i.e. through a build-essential package), you can create documentation natively, without needing docker.

You can run these commands locally:

composer install
make docs

The provided Symfony Commands can be executed via:

./packages/typo3-guides-cli/bin/typo3-guides (migrate|lint-guides-xml|configure)

Repository split (subtree-split of this mono-repository)¶

To be listed on Packagist each package in the folder packages/ of this mono-repository has to have its own Git repository (called "subtree split"). On merging (push/commit) and creating tags, these subrepositories are automatically updated by the GitHub action .github/workflows/split-repositories.yaml.

To add a new split-repository package, the following is needed:

• Create a repository on GitHub with the matching Composer name, special signs replaced by minus.
• Configure the repository with maintain rights to the group PHP-based-rendering-bot
• Add an entry to file config.subsplit-publish.json, formatted like the existing subtrees.
• Push some change within the correspondig package directory on the mono-repository's main branch.
• Add the new repository to Packagist.

Using Docker¶

A Docker image is available on GitHub packages. If you want to build your own image you can use the following command, in the root of this repository.

make docker-build

Once the build is finished you can execute your own image using:

docker run --rm -v $(pwd):/project typo3-docs:local --progress

For macOS you may need to specify the argument user:

docker run --rm -v $(pwd):/project --user=$(id -u):$(id -g) typo3-docs:local --progress

Using PHP¶

A phar binary is shipped with this repository. In short, a phar file is an executable PHP file. You can run it like any other executable.

To build the phar file we use Box_, with some wrapper script. To build the phar file yourself, you can run the following command.

make build-phar

This will create a file called guides.phar in the build directory. You can execute the phar file like a PHP file using:

php build/guides.phar

GitHub workflow¶

Developers contributing to the repository of this project on github_renderguides_ will trigger several GitHub Workflow when commiting/pushing code.

On terminology: A GitHub Workflow is something that is triggered within the repository (i.e. on a commit/tag). A GitHub Action is something that can be executed from the repository, where the repository allows other repositories to i.e. render the documentation. This repository provides both Workflows and Actions.

GitHub workflow: Commit/PR stragegy¶

The GIT main branch is protected, so only feature/bugfix/task-branches and forked repositories can be merged into it. When a Pull Request (PR) is created, at least one team member needs to approve it, so that it can be merged.

When a PR is created (and for every follow-up commit) the following GitHub Action are executed:

• .github/workflows/main.yaml runs code quality and integration checks
• .github/workflows/docker-self.yaml creates a test docker container image (not uploaded anywhere), only if the PR modifies the main Dockerfile.

Once a PR is merged, nothing else happens.

GitHub workflow: Release strategy¶

Whenever assets of our theme (packages/typo3-docs-theme) need to be uploaded, or the official Docker container needs to be updated, a GIT tag must be pushed to this repository.

The tag must be formatted as a semver-version string without a leading character, i.e. 0.1.0 or 5.1.1. We only support a progressive mainline of versions, so if a 5.0.0 version will come out at some point, backporting bugfixes to previous major versions is not planned.

If that ever needs to happen, also tags for older versions can be added to GIT to trigger building the relevant Docker container images. It is then very important that the most recent version is tagged LAST in this process, because only the last GIT tag is used for the latest Docker container:

# DO this:
git checkout 3.1.2
# .. cherry-pick bugfixes ..
# .. commit to a branch like release/3.1.3 ..
git tag 3.1.3 && git push --tags
git checkout main
# .. release the main version
git tag 4.0.0 && git push --tags

# do NOT do this:
git tag 4.0.0 && git push --tags
git checkout 3.1.2
# ...

When a GIT version tag matching *.*.* is pushed, these workflows are executed:

• .github/workflows/phar.yaml build the PHAR image for the release
• .github/workflows/docker.yaml build the Docker container image for the release, using the version tag.
• .github/workflows/deploy-azure-assets.yaml uploads the latest assets (everything in packages/typo3-docs-theme/resources/public) to the Azure cloud CDN, using the version tag.

GitHub workflow: GitHub Actions - Main entry¶

/action.yaml is the main entry point for a composite action. It can be used by other repositories in workflows.

The GitHub repository github_gh_render_action_ provides an easy interface to that action. That repository provides a wrapper to check if a documentation repository needs to be rendered using Sphinx (the old rendering, using a Settings.cfg file) or via phpDocumentor (the new rendering, using a : file:guides.xml file).

The central piece of that action is:

- uses: TYPO3-Documentation/render-guides@main
  id: render-guides
  if: steps.enable_guides.outputs.GUIDES == 'true'
  with:
    working-directory: t3docsproject
    config: ./t3docsproject/Documentation/
    output: ./RenderedDocumentation/Result/project/0.0.0
    configure-branch: ${{ env.source_branch }}
    configure-project-release: ${{ env.target_branch_directory }}
    configure-project-version: ${{ env.target_branch_directory }}

This "remotely executes" the /action.yaml of this repository with specific input parameters gathered earlier in the gh-render-action action.

All of this allows an extension author to provide a GitHub Workflow in their own repository like this:

jobs:
  render-documentation:
    runs-on: ubuntu-latest
    name: "Render Documentation for this repository and upload"
    steps:
      - name: Render Repository
        uses: TYPO3-Documentation/gh-render-action@main
        id: rendering
        with:
          repository_url: https://github.com/$GITHUB_REPOSITORY
          source_branch: main
          target_branch_directory: main

Then it does not even matter, if the repository uses the old or new rendering, everything is done through the intermediate layer of gh-render-action.

This will also in the future allow us to switch to different renderings or take care of breaking configurations, so that extension authors (and the TYPO3 core documentation) always can rely on one action that does not change, and does not need different version numbers/tags.

The /action.yaml composite action takes in the input of the code snippet above, and then executes two composite steps:

• .github/actions/configure-guides-step/action.yaml that provides extension-repository specific attributes that influence the local rendering. The input variables are dynamically injected into a temporary guides.xml file, that is used for the actual rendering. This is done by executing our own latest Docker container image.
• .github/actions/render-guides-step/action.yaml is the actual rendering step, also using the same latest Docker container image.

Note that we only have one central Docker container image entrypoint that can take arguments like migrate or render to trigger different actions.

GitHub workflow: deploy-azure-assets¶

.github/workflows/deploy-azure-assets.yaml is triggered when a GIT tag matching *.*.* is committed to the repository.

It checks out this repository, retrieves the current GIT tag, gathers all files in packages/typo3-docs-theme/resources/public and moves them to a directory structure like cdn/cdn/theme/typo3-docs-theme/1.0.0/ (using the version number that has been used in the GIT tag).

That directory structure is then uploaded to azure, by using the secret GIT environment variables configured in our repository.

GitHub workflow: docker¶

.github/workflows/docker.yaml is triggered when a GIT tag matching *.*.* is committed to the repository.

It does these steps:

• build: Sets up a matrix of docker platforms (arm, amd) to be built. This results in three build steps in total, once per platform: - Check out the repository with the current GIT tag - Retrieve Docker metadata (tags, versions) - Initiates the Docker build chain - Store the currently used GIT tag (version number) in an environment variable TYPO3AZUREEDGEURIVERSION. See description below. - Create the docker image, using the environment variable.
• merge: Then the three builds are merged and uploaded to the gchr docker registry.

The variable TYPO3AZUREEDGEURIVERSION is very important to be baked into the Docker image. This will ensure, that the rendering for remote repositories is always performed with the matching version number of both the theme and the Docker image. All assets can then be referenced as https://typo3.azureedge.net/typo3documentation/theme/typo3-docs-theme/$TYPO3AZUREEDGEURIVERSION/img/typo3-logo.svg.

Note that the version is used here, not a string like main or stable as the version, because CDNs would always cache these files and probably not deliver a new version, because the URI would be the same.

This means, the latest Docker image container will always reference to the CDN with the most recent version number. If at some point incompatibilities in the rendering are introduced, we can separate the gh-render-action repository in a way, that could reference exact Docker images other than latest, like by referring to a :5.0 image (using 5.0.1 / 5.0.2 / ... CDN URIs), or even using :5 to reference to the most recent 5.x version.

GitHub workflow: docker-test¶

.github/workflows/docker-test.yaml is triggered whenever a commit changes the Dockerfile.

The workflow step then uses that modified Dockerfile and tries to build it, and just execute the resulting container.

Note that no Docker container is actually uploaded. All the GitHub actions are just executed with the locally built docker container in this case, because this workflow step replaces the Docker container image name to the local Dockerfile instead of a registry URI.

A limitation currently is that the local Docker image will always use the action steps to configure and render the documentation from the main repository, not the fles that may be modified within the commit. See the note in .github/workflows/docker-test.yaml at the end for details.

GitHub workflow: main¶

.github/workflows/main.yaml is triggered on each commit and for each Pull Request (PR).

It performs basic code quality analysis and execution of unit/integration tests:

• Tests:

  • Run unit tests
  • Run integration tests

• Quality:

  • CGL
  • PHPSTAN
  • Lint guides.xml configurations
• Validate monorepo structure

GitHub workflow: phar¶

(work in progress)

.github/workflows/phar.yaml is triggered on each commit (not on Pull Requests). It builds the a phar archive that will be available for created releases.

Build Sources¶

To build the public assets execute the following commands:

ddev ssh
cd packages/typo3-docs-theme
npm ci
npm run build

Or use the custom ddev commands:

ddev npm-ci
ddev npm-build

Debug assets¶

You can build the assets for debugging with the following commands:

ddev ssh
cd packages/typo3-docs-theme
npm ci
npm run debug

Or use the custom ddev commands:

ddev npm-ci
ddev npm-debug

The generated assets are copied directly into Documentation-GENERATED-temp/_resources and source maps are not removed. Upon inspection in the browsers web developer tools you can therefore see in which source scss file certain styles were defined. Before committing you must run npm run build so that you can commit the generated asset files into the theme.

Interlinks to official manuals¶

By using suffixes the version of the manual to be linked can be specified:

*   :ref:`TYPO3 Explained, preferred version <t3coreapi:start>`
*   :ref:`TYPO3 Explained, main version (development) <t3coreapi/dev:start>`
*   :ref:`TYPO3 Explained, stable version (for example 12.4) <t3coreapi/stable:start>`
*   :ref:`TYPO3 Explained, old stable version (for example 11.5) <t3coreapi/oldstable:start>`
*   :ref:`TYPO3 Explained 12 LTS <t3coreapi/v12:start>`
*   :ref:`TYPO3 Explained 12.4 <t3coreapi/12.4:start>`

This would output:

• TYPO3 Explained, preferred version
• TYPO3 Explained, main version (development)
• TYPO3 Explained, stable version (for example 12.4)
• TYPO3 Explained, old stable version (for example 11.5)
• TYPO3 Explained 12 LTS
• TYPO3 Explained 12.4

<?xml version="1.0" encoding="UTF-8" ?>
<guides
    xmlns="https://www.phpdoc.org/guides"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
    <project title="Render guides"/>
    <extension
        class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
        typo3-core-preferred="stable"
    />
</guides>

<extension
    class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
    typo3-core-preferred="8.7"

<?xml version="1.0" encoding="UTF-8" ?>
<guides
    xmlns="https://www.phpdoc.org/guides"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
    <project title="Render guides"/>
    <extension
        class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
        typo3-core-preferred="stable"
    />
    <!-- explicitly link to version 8.7 of TYPO3 Explained -->
    <inventory id="t3coreapi_v8" url="https://docs.typo3.org/m/typo3/reference-coreapi/8.7/en-us/"/>
</guides>

*   :ref:`TYPO3 Explained, always version 8.7 <t3coreapi_v8:start>`

Interlinks to system extensions¶

You can link to the manual of a system extension: Use the extension's Composer name as interlink domain:

*   :doc:`Adminpanel <typo3/cms-adminpanel:Index>`
*   :ref:`RTE <typo3/cms-rte-ckeditor:introduction>`

This will be rendered as:

• Adminpanel
• RTE

By default they will link to your preferred TYPO3 version. You can link to another version by using the same prefixes as for official manuals:

*   :ref:`RTE <typo3/cms-rte-ckeditor/dev:introduction>`
*   :ref:`RTE <typo3/cms-rte-ckeditor/stable:introduction>`
*   :ref:`RTE <typo3/cms-rte-ckeditor/oldstable:introduction>`
*   :ref:`RTE <typo3/cms-rte-ckeditor/v12:introduction>`
*   :ref:`RTE <typo3/cms-rte-ckeditor/12.4:introduction>`
*   :ref:`RTE <typo3/cms-rte-ckeditor/v8:introduction>`
*   :ref:`RTE <typo3/cms-rte-ckeditor/8.7:introduction>`

This will be rendered as:

• RTE
• RTE
• RTE
• RTE
• RTE
• RTE
• RTE

For your convenience the changelog, situated in system extension typo3/cms-core can also be linked with the prefix changelog:

*   :ref:`Changelog: Remove jquery-ui <changelog:breaking-100966-1686062649>`

This will be rendered as:

• Changelog: Remove jquery-ui

Interlinks to third-party extensions¶

You can link to the manual of a third-party extension if that extension's manual has been rendered on https://docs.typo3.org.

To create an interlink to a third-party extension, use the extension's Composer name as interlink domain:

*   :doc:`News <georgringer/news:Index>`
*   :ref:`External Imports <cobweb/external_import:start>`

This will be rendered as:

• News
• External Imports

By default this will link to the main version of the manual. If you desire to link a specific version, you can attach the minor version (for example "11.3") separated by a slash:

*   :doc:`News <georgringer/news/11.3:Index>`
*   :doc:`External Imports <cobweb/external_import/7.2:Index>`

• News
• External Imports

If an extension author needs to link to a specific version of an extension's manual, they can define that version manually in the manual's guides.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<guides
    xmlns="https://www.phpdoc.org/guides"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
    <project title="Render guides"/>
    <extension
        class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
        typo3-core-preferred="stable"
    />
    <!-- explicitly link to stable versions of extensions -->
    <inventory id="georgringer/news/stable" url="https://docs.typo3.org/p/georgringer/news/11.3/en-us/"/>
    <inventory id="georgringer/news/stable" url="https://docs.typo3.org/p/cobweb/external_import/7.2/en-us/"/>
</guides>

*   :doc:`News <georgringer/news/stable:Index>`
*   :doc:`External Imports <cobweb/external_import/stable:Index>`

This will be rendered as:

• News
• External Imports

With official Docker container¶

To migrate your settings to the new rendering method, run the following command in your project's root folder:

docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest migrate Documentation

The last option is the folder (here: Documentation). When running the command from another folder than the project's root folder, adapt the given path accordingly.

With make¶

To migrate your settings to the new rendering method, run the following command in your project's root folder:

make migrate-settings path=Documentation

When running the command from another folder than the project's root folder, adapt the given path accordingly.

With ddev¶

To migrate your settings to the new rendering method, run the following command in your project's root folder:

ddev composer make migrate-settings path=Documentation

When running the command from another folder than the project's root folder, adapt the given path accordingly.

With PHP¶

To migrate your settings to the new rendering method, run the following command in your project's root folder:

packages/typo3-guides-cli/bin/typo3-guides migrate Documentation

The last option is the folder (here: Documentation). When running the command from another folder than the project's root folder, adapt the given path accordingly.