Rendering 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.
Run these commands in a terminal in the parent directory of the directory
Commands to Render Documentation¶
Make dockrun_t3rd available in current terminal
source <(docker run --rm t3docs/render-documentation show-shell-commands)
If this command does not work on your platform, look at Problems with source < (docker run ... for alternatives.
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.
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:
The numbers correspond to the steps:
Prepare dockrun_t3rd: This will run the Docker container, in order to make the command
dockrun_t3rdavailable in your current terminal. You must do this again for every new terminal you open.
Render the documentation: This will automatically find the documentation in the
Documentationsubfolder. It will create a directory
Documentation-GENERATED-tempand write the results there.
View the documentation: You can now view the rendered documentation in your browser.
On Mac use
openand on Windows
Look at the hints that are shown in the terminal. If you structured the documentation correctly,
Index.rstis always on the top level directory under the directory
Documentation. The renderer will create the file
Index.htmlfrom that. The path is always the same.
If the open command does not work for you, create a URL you can open:
When you make additional changes, you can run step 2 again and reload the page in your browser.
Create aliases for the commands that work for you. Or add them to your profile. Example aliases are also listed in 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 documenation and open result in browser alias t3doc='t3docrun && t3docmake && t3docopen'