Requirements
- Docker must be installed and running
- Linux or MacOS (I have not tested Windows)
- Documentation according to the official TYPO3 guidelines (see how-to-document-an-extension)
Step for stop
Step 1: Start Docker Image and make command available in Terminal
Open the terminal and execute the command in the parent directory of the documentation:
source <(docker run --rm t3docs/render-documentation show-shell-commands) Step 2: Render documentation
If I want to view the documentation as HTML, I execute the following command:
dockrun_t3rd makehtml
As a result you get the HTML output in the directory: /Documentation-GENERATED-temp/Result/project/
If the whole thing is to be created as a PDF, the following commands must be executed:
dockrun_t3rd makeall
dockrun_t3rd makehtml -c make_latex 1 -c make_pdf 1 In addition to the HTML output, this also generates a latex output that is used in the third step.
Step 3: Conversion to PDF
Finally, three more commands are issued to generate the PDF.
mkdir -p Documentation-GENERATED-temp
docker run --rm \
-v $(pwd):/PROJECT:ro \
-v $(pwd)/Documentation-GENERATED-temp:/RESULT \
t3docs/render-documentation:develop \
makeall -c jobfile /PROJECT/Documentation/jobfile.json
docker run --rm \
-v $(pwd)/Documentation-GENERATED-temp/Result/latex:/RESULT \
--workdir="/RESULT/" \
thomasweise/docker-texlive-full:latest \
"./run-make.sh" The result is then in the directory: /Documentation-GENERATED-temp/Result/latex/PROJECT.pdf
Conclusion
With the help of the Docker environment, not only PDF files can be rendered, but also the documentation of a TYPO3 extension can be tested in advance. Although the Rst format is more complex than Markdown, it offers many more possibilities to create comprehensive documentation with navigation and cross-linking.
