Render documentation with the TYPO3 theme 

You can render documentation by executing the following command in the folder that contains the Documentation folder:

Execute in extension root, the directory that contains your extensions composer.json 
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
Copied!

Open the file saved to Documentation-GENERATED-temp/Index.html in a browser of your choice.

The official manuals commonly contain a make file. You can use the short command:

make docs
Copied!

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:

  1. Clone the repository containing the documentation.
  2. Navigate to the extension's root folder, the directory which contains the composer.json.

  3. Check if there is documentation to be rendered:

    A folder called Documentation containing at least the files Index.rst and guides.xml.

  4. Choose your preferred method of rendering (See below):

Make sure that Docker is installed on your system.

Execute in extension root, the directory that contains your extensions composer.json 
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
Copied!

Open the file saved to Documentation-GENERATED-temp/Index.html in a browser of your choice.

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:

.github/workflows/documentation.yml 
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 --minimal-test
Copied!
.gitlab-ci.yml 
stages:
  - test

test_documentation:
  stage: test
  image:
    name: ghcr.io/typo3-documentation/render-guides:latest
    entrypoint: [""]
  script:
    - mkdir -p Documentation-GENERATED-temp
    - /opt/guides/entrypoint.sh --config=Documentation --no-progress --minimal-test
Copied!