Developers¶

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.

Under the hood this tool is based on phpDocumentor/guides

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

The most common commands are probably:

# Render documentation
make docs

# Run tests
make test

# (Re)-Create Docker container
make docker-build

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

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

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

All these options are provided to allow for maximum convenience for any contributor and the GitHub pipelines, while internally only using Makefile syntax.