For coders TYPO3 Tech Corner

Render PDF of RST Doc documentation

Render PDF of RST Doc documentation

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.

Back

"Code faster, look at the time" - does this sound familiar to you?

How about time and respect for code quality? Working in a team? Automated tests?

Join us