Note
This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.
If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.
Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.
Render documentation with the TYPO3 theme¶
Rendering the Documentation folder locally with Docker¶
You can render the documentation of an official TYPO3 manual or a third-party manual with the following steps:
- Clone the repository containing the documentation.
- Navigate to the extension's root folder, the directory which contains the composer.json.
-
Check if there is documentation to be rendered:
A folder called Documentation containing at least the files Index.rst and guides.xml.
- Choose your preferred method of rendering (See below):
Make sure that Docker is installed on your system.
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
.
mkdir -p Documentation-GENERATED-temp
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
xdg-open "Documentation-GENERATED-temp/Index.html"
mkdir -p Documentation-GENERATED-temp
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
open "Documentation-GENERATED-temp/Index.html"
New-Item -ItemType Directory -Force -Path ".\Documentation-GENERATED-temp"
docker run --rm --pull always -v ${PWD}:/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
start "Documentation-GENERATED-temp/Index.html"
Publishing extension documentation to docs.typo3.org¶
For your documentation to be published to https://docs.typo3.org, your TYPO3 extension has to have a valid composer.json and either a folder called Documentation with a Documentation/Index.rst and a Documentation/guides.xml or a README.rst / README.md in the extension's root directory.
The extension has to be publicly available on GitHub or GitLab. You have to establish a Webhook and the Documentation Team has to approve your first rendering.
Introduce automatic testing for extension documentation¶
It is recommended to make sure your documentation always renders without warning. On GitHub or GitLab you can introduce actions that test your documentation automatically:
name: test documentation
on: [ push, pull_request ]
jobs:
tests:
name: documentation
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Test if the documentation will render without warnings
run: |
mkdir -p Documentation-GENERATED-temp \
&& docker run --rm --pull always -v $(pwd):/project \
ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log
stages:
- test
test_documentation:
stage: test
script:
- mkdir -p Documentation-GENERATED-temp
- docker run --rm --pull always -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log
tags:
- docker