Helper function 'dockrun'¶
It takes rather long and complicated Docker with many parameters to get the
various things done. The helper function makes assembling these commands an
easy job. dockrun_t3rd is an abbreviation of
Docker-run-TYPO3-render-documentation.
Contents
Define the function¶
Define the function in your terminal window:
~: #
~: eval "$(docker run --rm t3docs/render-documentation:develop show-shell-commands)"
This function is now defined FOR THIS terminal window to run 'latest':
dockrun_t3rd
In effect, you can now use command dockrun_t3rd instead of docker run --rm
t3docs/render-documentation.
Basic usage¶
Show minimal help:
~: dockrun_t3rd
t3rd - TYPO3 render documentation (develop, v3.0.dev23)
For help:
docker run --rm t3docs/render-documentation:latest --help
# or, if you defined the helper function:
dockrun_t3rd --help
... did you mean 'dockrun_t3rd makehtml'?
See manual: https://t3docs.github.io/DRC-The-Docker-Rendering-Container/
Show help:
dockrun_t3rd --help
Render documentation:
# .
# └── PROJECT <- start here!
# └── Documentation
cd PROJECT
dockrun_t3rd makehtml-no-cache
See the code¶
Display the code:
docker run --rm t3docs/render-documentation show-shell-commands
Display the code:
dockrun_t3rd show-shell-commands
If the function is defined, you may read back the code from the shell as the shell has understood it:
~: declare -f dockrun_t3rd
dockrun_t3rd () {
local DEBUG=${T3DOCS_DEBUG:-0}
local DRY_RUN=${T3DOCS_DRY_RUN:-0}
local git_restore_mtime=$(which git-restore-mtime)
local exitcode=$?
if [[ $exitcode -ne 0 ]]
then
[…]
The function is only defined for the current terminal session.
The code starts like this:
# NOTE
# Run this 'eval' command at the command line to define the helper
# function for the current terminal:
# eval "$(docker run --rm t3docs/render-documentation:develop show-shell-commands)"
#
# As alternative, you can 'source' the code directly into the shell:
# source <(docker run --rm t3docs/render-documentation:develop show-shell-commands)
# ATTENTION:
# No whitespace between '<('
#
# Or, use an intermediate file:
# docker run --rm t3docs/render-documentation:develop show-shell-commands >shell-commands.sh
# source shell-commands.sh
# This function defines the helper function, usually named \'dockrun_t3rd\'
function dockrun_t3rd () {
# Environment variables the USER may find important (on the host!),
# no slash ('/') at the end,
# default is the current directory $(pwd):
#
# T3DOCS_PROJECT=/abspathto/MyProjectStartFolder (readonly)
# T3DOCS_RESULT=/abspathto/ResultFolder (readwrite)
# T3DOCS_TMP=/abspathto/TemporaryFolder (readwrite)
# T3DOCS_THEMES=/abspathto/MySphinxThemes (readonly)
#
# Environment variables only some DEVELOPERS may find important,
# no slash ('/') at the end,
#
# T3DOCS_MAKEDIR=/abspathto/MYALL/Makedir
# T3DOCS_MENU=/abspathto/MYALL/Menu
# T3DOCS_TOOLCHAINS=/abspathto/MYALL/Toolchains
# T3DOCS_USERHOME=/abspathto/MYALL/userhome
# T3DOCS_VENV=/abspathto/MYALL/venv
# T3DOCS_WHEELS=/abspathto/WheelsFolder
# T3DOCS_DEBUG=0 (0 or 1, talk to stdout)
# T3DOCS_DRY_RUN=0 (0 or 1, don't really execute)
[…]
T3DOCS_DEBUG¶
The function is looking for various shell variables. If condition
$T3DOCS_DEBUG=1 is met, some extra debug output will be shown.
Turn debug info on permanently in the current terminal window and use the function:
export T3DOCS_DEBUG=1
dockrun_t3rc …
Or turn debugging on for just a single run:
T3DOCS_DEBUG=1 dockrun_t3rd makehtml-no-cache
Example:
~: T3DOCS_DEBUG=1 dockrun_t3rd makehtml-no-cache
PROJECT......: /home/user/Repositories/github.com/t3docs/DRC-The-Docker-Rendering-Container
creating: mkdir -p /home/user/Repositories/github.com/t3docs/DRC-The-Docker-Rendering-Container/Documentation-GENERATED-temp
RESULT.......: /home/user/Repositories/github.com/t3docs/DRC-The-Docker-Rendering-Container/Documentation-GENERATED-temp
OUR_IMAGE....: t3docs/render-documentation:latest
/home/user/bin/git-restore-mtime
147 files to be processed in work dir
Statistics:
0.08 seconds
2,147 log lines processed
398 commits evaluated
147 updated files
10 updated directories
docker run --rm --user=1000:1000 \
-v /user/marble/Repositories/github.com/t3docs/DRC-The-Docker-Rendering-Container:/PROJECT:ro \
-v /user/marble/Repositories/github.com/t3docs/DRC-The-Docker-Rendering-Container/Documentation-GENERATED-temp:/RESULT \
t3docs/render-documentation:develop makehtml-no-cache
==================================================
10-Toolchain-actions/run_01-Start-with-everything.py
exitcode: 0 65 ms
==================================================
10-Toolchain-actions/run_02-Show-help-and-exit.py
exitcode: 0 62 ms
[…]
T3DOCS_DRY_RUN¶
Don't use.
T3DOCS_PROJECT¶
Instead of using the current folder you may specify the absolute path to a project. This means, you can start the rendering from anywhere.
Example:
export T3DOCS_PROJECT=/home/user/Repositories/github.com/t3docs/DRC-The-Docker-Rendering-Container
dockrun_t3rd makehtml-no-cache
T3DOCS_RESULT¶
You can send the rendering result to a folder of your choice.
However, the container will always create the final subfolder
Documentation-GENERATED-temp/ by itself, so it can be sure it not overwriting
something important on the host. The means, the result will actually be in
${T3DOCS_RESULT}/Documentation-GENERATED-temp.
Example:
export T3DOCS_RESULT=/home/user/temp
dockrun_t3rd makehtml-no-cache
# result will be in /home/user/temp/Documentation-GENERATED-temp