How to render documentation¶
This page explains how to render a manual locally on your machine with Docker in order to test the rendering.
Run these commands in a terminal in the parent directory of the directory
Documentation
. You should use a bash compatible shell, if possible.
If you run into a problem while rendering, check Troubleshooting local rendering with Docker, report an issue or ask for help.
Install Docker: https://docs.docker.com/install/
Preparations
The docker image is not listed on Docker Hub (hub.docker.com) anymore, therefore some preparations need to be done once:
# pull 'latest' version from GitHub container repository docker pull ghcr.io/t3docs/render-documentation # The "real" tag is independent of the container repository, # so let's just create that extra "real" and "generic" tag docker tag ghcr.io/t3docs/render-documentation t3docs/render-documentation # At the moment the 'latest' version is actually a renamed 'v3.2.1' version # and as such internally references 'v3.2.1'. So make that available too. docker tag t3docs/render-documentation t3docs/render-documentation:v3.2.1 # verify it worked docker run --rm t3docs/render-documentation --version
Make 'dockrun_t3rd' available in current terminal
eval "$(docker run --rm t3docs/render-documentation show-shell-commands)" alias dockrun_t3rd="dockrun_v3.2.1 $@"
This will run the Docker container and print out shell code. Once "eval-uated" the code defines a helper function named
dockrun_v3.2.1
, which is then also aliased asdockrun_t3rd
. This function relieves you of the work of setting the volumes and rights correctly when running the container and ensures a folder for the rendering results is provided. Executing the code witheval
defines the function for your current terminal. Don't forget the quotes around everything that goes into eval. Either define the function each time you open a new terminal window or add the line to the startup file of your shell like~/.bashrc
or.zshrc
.Run dockrun_t3rd
dockrun_t3rd makehtml
This will automatically find the documentation in the
Documentation
subfolder. It will create a directoryDocumentation-GENERATED-temp
and write the results there.Open generated documentation
Look at the output of the previous command to see where the generated documentation is located or use one of these commands to directly open the start page in a browser:
xdg-open "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html"
open "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html"
start "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html"