Troubleshooting

Mac: Assign enough RAM

  • On Mac OSX assign at least 4 GB RAM to Docker if you want to render really huge manuals like the TYPO3 Core changelog. Otherwise the rendering will just crash without meaningful error message because files cannot be written. Final result is reported as "Failure, because HTML could not be created.".

No documentation found!

Problem:

Near then end of the terminal output you see something like:

ATTENTION:

   No documentation found!

   Reason:
   None of the following starting files ("masterdoc") were found, no matter what
   mixture of lower and upper case was tried. In order of precedence:

      1. Documentation/Index.rst
      2. Documentation/index.rst
      3. Documentation/Index.md
      4. Documentation/index.md
      5. README.rst
      6. README.md

Solutions:

Did you start the rendering in the proper folder? Let's assume you have the folders PROJECT/Documentation. You need to start the rendering in the parent folder of ./Documentation. So go to PROJECT and try again.

command not found: dockrun_t3rd

Problem:

The helper function dockrun_t3rd has not yet been defined in this terminal window. Read more in chapter Quickstart.

The helper functions helps compiling docker run commands which may be long, complicated and intimidating, like, for example:

docker run --rm --user=1000:1000 \
   -v ~/Repositories/github.com/t3docs/DRC-The-Docker-Rendering-Container:/PROJECT:ro \
   -v ~/Repositories/github.com/t3docs/DRC-The-Docker-Rendering-Container/Documentation-GENERATED-temp:/RESULT \
   t3docs/render-documentation:develop makehtml-no-cache

command not found means that the helper function has not yet been defined in this instance of a terminal window.

Solution:

Define the function:

~  eval "$(docker run --rm t3docs/render-documentation show-shell-commands)"

This function is now defined FOR THIS terminal window to run 'latest':
    dockrun_t3rd

If you add the defining line to your shell's startup file the function will always be defined.