Rendering the documentation with Docker

Here, we show the basic rendering commands for rendering locally with the official Docker container.

These commands work best on Linux, but may also work on Mac or Windows (depending on your system). 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.

Run these commands in a terminal in the parent directory of the directory Documentation.

Prerequisites

Install Docker:

Commands to render the documentation

  1. Make dockrun_t3rd available in current terminal

    source <(docker run --rm t3docs/render-documentation show-shell-commands)

    Tip

    If this command does not work on your platform, look at Problems with source < (docker run ... for alternatives.

  2. Run dockrun_t3rd

    Please use this command in the parent folder of your documentation. In most cases you will have a folder Documentation. You must run this command one level above.

    dockrun_t3rd makehtml

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

Explanations

The numbers correspond to the steps:

  1. Prepare dockrun_t3rd: This will run the Docker container, in order to make the command dockrun_t3rd available in your current terminal. You must do this again for every new terminal you open.

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

  3. View the documentation: You can now view the rendered documentation in your browser.

    On Mac use open and on Windows start instead of xdg-open.

    Look at the hints that are shown in the terminal. If you structured the documentation correctly, Index.rst is always on the top level directory under the directory Documentation. The renderer will create the file Index.html from that. The path is always the same.

    If the open command does not work for you, create a URL you can open:

    echo "file://"$(pwd)/"Documentation-GENERATED-temp/Result/project/0.0.0/Index.html"

When you make additional changes, you can run step 2 again and reload the page in your browser.

Example aliases

Tip

Create aliases for the commands that work for you. Or add them to your profile. Example aliases are also listed in Aliases & Git Aliases.

It might also be a good idea to create command shortcuts in your IDE.

# run docker container and source shell commands
alias t3docrun='source <(docker run --rm t3docs/render-documentation show-shell-commands)'

# build docs
alias t3docmake='dockrun_t3rd makehtml'

# open generated docs in browser (uses t3open alias, see above)
# - use xdg-open for Linux
# - use open for Mac instead !!!
alias t3docopen='xdg-open "file:///$(pwd)/Documentation-GENERATED-temp/Result/project/0.0.0/Index.html"'

# remove generated docs
alias t3docclean='rm -rf Documentation-GENERATED-temp/'

# --- combined aliases ---

# run docker, generate documentation and open result in browser
alias t3doc='t3docrun && t3docmake && t3docopen'