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.

  1. Install Docker: https://docs.docker.com/install/

  2. 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
    
  3. 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 as dockrun_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 with eval 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.

  4. Run dockrun_t3rd

    dockrun_t3rd makehtml
    

    This will automatically find the documentation in the Documentation subfolder. It will create a directory Documentation-GENERATED-temp and write the results there.

  5. 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"