Quickstart

This page is for Linux and Mac.

Preparations

Verify you have Docker installed:

➜  ~ docker --version
Docker version 19.03.4, build 9013bf583a

➜  ~

Go to a project. Go to the top folder project/ of your project, DO NOT go to project/Documentation/, if you have that:

cd ~/project

You don't have a project at hand? Create a minimal one with just one file named README.rst:

# create project folder
mkdir ~/project

# go to there
cd ~/project

# Type a headline and a sentence to that file
echo 'My dummy project'  > README.rst
echo '================' >> README.rst
echo                    >> README.rst
echo 'Hello world, this is my splendid documentation.' >> README.rst

Build HTML using 'dockrun_t3rd'

'dockrun_t3rd' is just a handy helper function to run the Docker command for t3rd, that is: TYPO3 render documentation. This function can make your life much easier, so please give it a try!

1. Create a place to store a shell file to. We recommend .dockrun/dockrun_t3rd in your home directory. Create a shell-commands.sh file there that can afterwards be used to define a helper function. To do that import that file in a shell session by means of the source command. To always do that automatically, add an appropriate line to your BASH or ZSH startup file. How it can be done:

   # create a folder to keep things
   mkdir -p ~/.dockrun/dockrun_t3rd
   
   # create the file with shell commands there
   docker run --rm t3docs/render-documentation:v2.3.0 \
      show-shell-commands   > ~/.dockrun/dockrun_t3rd/shell-commands.sh
   
   # import the commands in a shell session
   source ~/.dockrun/dockrun_t3rd/shell-commands.sh
   
   # optional: add the command to your startup file
   echo 'source ~/.dockrun/dockrun_t3rd/shell-commands.sh' >> ~/.bashrc
   echo 'source ~/.dockrun/dockrun_t3rd/shell-commands.sh' >> ~/.zshrc
   

   Tip: On most Linuxes you can source the shell commands directly without and intermediate file like so. This has been reported to not work on Macs:

   source <(docker run --rm t3docs/render-documentation:v2.3.0-local show-shell-commands)
   

2. Go to the project and run the rendering:

   cd ~/project
   
   dockrun_t3rd  makehtml
   
   # or
   
   dockrun_t3rd  makeall
   

   Ask the container for help:

   ➜  ~ dockrun_t3rd
   
   t3rd - TYPO3 render documentation (v2.4.0-dev)
   For help:
      docker run --rm t3docs/render-documentation:v2.4.0-dev --help
      dockrun_t3rd --help
   
   ... did you mean 'dockrun_t3rd makehtml'?
   
   See manual (draft) at
   https://docs.typo3.org/m/typo3/t3docs-docker-render-documentation/draft/en-us/
   
   
   ➜  ~ dockrun_t3rd --help
      # lots of lines ...
   
   
   ➜  ~
   

Build HTML with plain Docker commands

Attention: You need to replace the project path /home/marble/project with whatever is valid in your case:

# Go to the project
cd ~/project

# Create result folder
mkdir Documentation-GENERATED-temp

# Run the rendering
docker \
   run --rm --user=$(id -u):$(id -g) \
   -v /home/marble/project:/PROJECT:ro \
   -v /home/marble/project/Documentation-GENERATED-temp:/RESULT \
   t3docs/render-documentation:v2.3.0 \
   makehtml

Attention

Make sure you map PROJECT in readonly mode. This will protect your files from being damaged in case something is going wrong with the complex machinery inside the container. It shouldn't happen. But who knows?

About the Docker command: Note that the project is mapped as /PROJECT:ro which means readonly mode. Results are created in /RESULT, so this folder is mapped in normal readwrite mode. --rm means that the container is to be removed right after it has been run. Otherwise a useless copy of the image would be left on disk each time the command is run. The pulled Docker image is not affected by the --rm option. With --user= we make sure that the created output files do belong to the actual user and not to the super user.