DDEV TYPO3 Documentation (standalone)

Overview

TYPO3 projects and extensions can use a common TYPO3 Documentation rendering. It is based on the ReST markup syntax standard.

The documentation is rendered via the render-guides project, which is a PHP-based customization of the phpDocumentor guides sub-project.

render-guides offers a convenient docker image which allows to perform local rendering.

That docker image is utilized by this DDEV addon to provide a documentation component to a project.

Any documentation of a DDEV project adhering to the TYPO3 ReST syntax within a subdirectory Documentation can then be accessed via the http://<project>.ddev.site:1337/ sub-domain and will show that rendered documentation.

Note

Please note that proper hot-reloading currently only works with http:// scheme, not https://, which ddev describe shows by default.

The local server providing this rendered documentation is capable of hot-reloading / live document preview / watch mode. That means, any changes made to the raw source *.rst files will be immediately reflected in the browser.

That way, you do not need to manually re-trigger rendering of documentation after every change, and you can have a browser-window next to your editing interface of the ReST files to see your results in real-time, like WYSIWYG (What You See Is What You Get).

Installation

Caution

The live rendering is currently experimental. Use at your own risk. Side effects could be (not that we know of ywr): Deletion of files in /Documentation/, memory leaks on long runtime, resource exhaustion. Please report any bugs you find!

Prerequisites:

• A DDEV project directory with existing or fresh configuration
• A Documentation/ subdirectory with ReST files as shown in TYPO3 How To Document
• A bash shell in your project directory ready to execute the following command:

ddev add-on get TYPO3-Documentation/ddev-typo3-docs
ddev restart

Important

For now this add-on is not yet pushed to the official DDEV add-on registry

Note

You can also pick a different rendering container, like local ones or older / newer versions. For example when the underlying "render-guides" image is created as "typo3-docs:local" container (via make vendor). Then that container needs to be utilized via the base-image flag:

ddev dotenv set .ddev/.env.typo3-docs-build --render-guides-base-image="typo3-docs:local"

After installation, make sure to commit the .ddev directory to version control and commit any changes the addon installation has made.

Then you can see your rendered documentation via:

ddev launch :1337

Note

(Ensure you're using http for now!)

Usage

Command	Description
ddev launch :1337	Open rendered documentation in your browser (http://<project>.ddev.site:1337)
ddev describe	View service status and used ports for documentation
ddev logs -s typo3-docs	Check documentation logs

Configuration

Everything is aimed to be executed with zero-configuration.

However, you can adapt:

• HTTP(s) port of the local rendering server (default: 1337)
• Target documentation directory (default: Documentation)
• Additional "render-guides" CLI arguments
• Use Docker container (to test with local container builds)

This is achieved via ENV (Environment) variables in your .ddev/config.yaml file:

Variable	Flag	Default
RENDER_GUIDES_BASE_IMAGE	--render-guides-base-image	ghcr.io/typo3-documentation/render-guides:latest
RENDER_GUIDES_PORT	--render-guides-port	1337
RENDER_GUIDES_DOCS_PATH	--render-guides-docs-path	Documentation
RENDER_GUIDES_ARGS	--render-guides-args	--verbose

You can set these environment variables inside a file like .ddev/env.typo3-docs-build:

RENDER_GUIDES_BASE_IMAGE="typo3-docs:local"
RENDER_GUIDES_PORT=4711
RENDER_GUIDES_DOCS_PATH=docs
RENDER_GUIDES_ARGS="--verbose --no-progress"

All arguments that can be passed through RENDER_GUIDES_ARGS on to the container can be seen via:

docker run --rm -it --entrypoint sh -v ./:/project/ ghcr.io/typo3-documentation/render-guides:latest
php /opt/guides/bin/guides --help

Credits

Maintained by @TYPO3-Documentation