This guide contains information about the render-guides tool and how to use it
as a documentation writer. It also contains information for developers who want
to extend the tool.
This guide contains information about the render-guides tool and how to use it
as a documentation writer. It also contains information for developers who want
to extend the tool.
This is the documentation rendering tool for TYPO3 projects. It is based on
phpDocumentor/guides and can be used as a drop-in replacement for Sphinx.
The tool is used by the automated documentation rendering system of the
TYPO3 project. And can be used by documentation authors to validate their
documentation.
Note
This tool is still in development, there will be bugs and missing features.
If you are looking for the current way to render documentation head over to
How to document.
This project is not a TYPO3 extension, but a standalone application
used to render documentation. If you want to learn more about how to write
documentation, please check the
Contributing Guide - How to Document.
Multiple methods are provided to install the project on your local machine.
You can choose whatever is easiest for you:
Using Docker natively, with a provided official container
Using Docker natively, with a locally-generated container
Using DDEV (utilizing Docker)
Using PHP
Note
The Docker container is the recommended way to use this project for
end-users. It will automatically set up all dependencies and will not interfere
with your local PHP installation or project. The container can be
used in any project (and in any GitHub action) without further dependencies.
Tip
Did you know: Instead of the docker client you can also use
the lightweight drop-in replacement Podman to run
the mentioned containers by replacing all docker commands in the
following steps with podman.
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.
Note
The Docker container internally contains a tagged release version of
this repository, and use that version as well to reference asset
URIs of the theme on our CDN.
docker run --rm -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest --progress --config ./Documentation
Copied!
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:
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
Copied!
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]
Copied!
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 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
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
Copied!
The provided Symfony Commands can be executed via:
This part of the documentation is meant for developers working on the render-guides
project. You will find information about the setup of the project and the release
process.
The repository ships a wide range of commands that are used to render the documentation,
build and execute development helpers, and they can be utilized by GitHub Actions.
The "single source of truth" for these commands is within the Makefile. You can
see all available commands via:
make help
Copied!
The most common commands are probably:
# Render documentation
make docs
# Run tests
make test
# (Re)-Create Docker container
make docker-build
Copied!
Most make commands can be prepended or appended with the parameter ENV=local:
# Render documentation
make docs ENV=local
# Run tests
make test ENV=local
# (Re)-Create Docker container
make docker-build ENV=local
Copied!
By default most make commands all utilize Docker to run within a container.
If the parameter ENV=local is appended or prepended to the command, they can
also be run locally, without Docker. This can speed up processing and saves
resources on build pipelines. This requires PHP on your host.
The Makefile can also be executed via composer. All commands in the
make range are just passed onto the Makefile via a composer script,
and automatically then use the ENV=local scope:
# Render documentation
composer make docs
# Run tests
composer make test
# (Re)-Create Docker container
composer make docker-build
Copied!
If your local environment does not provide make (usually a package like
build-essential) you can use DDEV to wrap the same commands within the DDEV container:
# Render documentation
ddev composer make docs
# Run tests
ddev composer make test
Copied!
All these options are provided to allow for maximum convenience for any contributor
and the GitHub pipelines, while internally only using Makefile syntax.
This repository is following a mono-repo setup. This means all code and
configuration to render documentation is in this repository. This includes
scripts to build the documentation and the configuration for the CI/CD pipeline.
Some packages in this repository can be used as standalone packages when not
rendering documentation for TYPO3, but for internal company documentation.
To ensure the mono-repo setup works, and also works in separate repositories,
we are using a tool called monorepo-builder. This tool will help us to keep
the dependencies over packages in sync.
If you add a new dependency to a package, you can run
make monorepo
Copied!
This will update the root composer.json file with the new dependency.
It is recommended to run the validation check before you commit:
make test-monorepo
Copied!
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.
The .ddev/ directory contains the configuration for the local development
environment for people using DDEV.
The .github/ directory contains the configuration for the GitHub workflows.
They are triggered by pull requests and pushes to the main branch. The main workflow
contains the quality assurance steps. The phar workflow builds the phar file on
release and nightly builds. Same applies for the Docker workflow on the docker side.
The bin/ directory contains the executable scripts for the project. The
file in there is needed for the phar build.
The packages/ directory contains the TYPO3-specific extensions. The
typo3-docs-theme extension contains the theme for the documentation, and
TYPO3-specific directives. The typo3-guides-extension extension contains
extensions on the base tool. This are customizations to make the tool fit the
TYPO3 documentation needs. The typo3-guides-cli package is a collection
of Symfony Commands for tasks like conversion or linting.
The tests/ directory contains the tests for the project. The integration
tests are located in the Integration/ directory. During the integration
tests the tool is executed as it was run by the user.
The tools/ directory contains the tools needed for the project. Like
scripts to build the phar file or adapt GIT hooks.
The Documentation/ directory holds the documentation you are now
reading. It is the default documentation being build by the project, too.
The Dockerfile and entrypoint.sh files provide the Docker
container support for the project.
The Makefile contains a list of all supported development commands and
tasks that can be executed. All of them can also be executed with a composer
wrapper script (composer make ...).
While the components of this repository are split into separate packages, it can
be build as a standalone application. Two ways are provided to use this project
on your own environment.
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
Copied!
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
Copied!
Warning
Currently, Box is not able to build a phar file for projects containing
Composer plugins as it will only install production dependencies. This
means that the composer.json is modified during the build process.
You shall not commit this change to the repository.
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.
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.
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
# ...
Copied!
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.
/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).
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
Copied!
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/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/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/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/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.
When contributing please run all tests before committing:
# Using Makefile (append ENV=localif you don't utilize docker)
make pre-commit-test
# Using composer (also uses "make" command internally, your OS may need a# package like "build-essential")
composer make pre-commit-test
# Using ddev
ddev composer make pre-commit-test
Copied!
You can use a helper script to set this up once in your project, so that
these checks are performed before any Git commit:
# Using Makefile
make githooks
# Using composer
composer make githooks
# Using ddev
ddev composer make githooks
Copied!
Those Git hooks will also check your commit message for line length.
The theme provided by this package is prepared to be integrated into the TYPO3
documentation website. Templates are written in Twig and uses components
provided by phpDocumentor/guides. The theme is using Bootstrap as a
base framework. You can find the theme in packages/typo3-docs-theme.
Templates can be found in packages/typo3-docs-theme/resource/template/.
To customize the components provided by phpDocumentor/guides you have to follow
the directory structure of the templates provided by this package. Every template
can be overwritten by creating a new template with the same name in the same
directory. The template engine will automatically use the new template.
In the template you always have the current node available. This
node is the element that is currently rendered. The node is an instance of
phpDocumentor\Guides\Nodes\Node. Every template has a different specialized
node. Consult the template of the node to see which properties are available.
When you are creating a template for a node that is a container (like a chapter)
you can access the children of the node by using node.children. This is an
array of nodes. You can iterate over this array to render the children using the
render_node function. This function will render the node using the correct
template.
You can build the assets for debugging with the following commands:
ddev ssh
cd packages/typo3-docs-theme
npm ci
npm run debug
Copied!
Or use the custom ddev commands:
ddev npm-ci
ddev npm-debug
Copied!
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.
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>`
It is not necessary anymore to list each of the standard inventories in the
guides.xml anymore. If desired you can override or redefine standard interlink
inventories or define new ones:
Documentation/guides.xml
<?xml version="1.0" encoding="UTF-8" ?><guidesxmlns="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"
><projecttitle="Render guides"/><extensionclass="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"typo3-core-preferred="stable"
/><!-- explicitly link to version 8.7 of TYPO3 Explained --><inventoryid="t3coreapi_v8"url="https://docs.typo3.org/m/typo3/reference-coreapi/8.7/en-us/"/></guides>
Copied!
The following link:
*:ref:`TYPO3 Explained, always version 8.7 <t3coreapi_v8:start>`
In the event of a change in long-term support, adjustments to the corresponding
TYPO3 versions can be made directly in the theme within the enum
\T3Docs\Typo3DocsTheme\Inventory\Typo3VersionMapping.
The default manuals to be supported can be managed in enum
\T3Docs\Typo3DocsTheme\Inventory\DefaultInventories.
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:
If you want to migrate from using Sphinx to render TYPO3 documentation
using the render-guides, the file Documentation/Settings.cfg has to be
replaced by an XML file, Documentation/guides.xml.
To facilitate migration the extension t3docs/typo3-guides-cli in this
mono-repository comes with a Symfony console command to automatically migrate
the outdated Settings.cfg.
After migration, you can add your guides.xml file to your custom repository,
and optionally also remove the old Settings.cfg file.
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.
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.