Windows users

About Linux, Mac, Windows: Please read the short chapter about operating systems.

Windows users, please contribute! Please help and contribute how you port measures and procedure of this manual to Windows.

A start to rewrite the 'dockrun_t3rd' script for PowerShell

If you are using Windows and Powershell, you can add the following function to your $PROFILE. For example, you can use code $PROFILE to edit the file. This is code for the PowerShell:

 1<#
 2.SYNOPSIS
 3    Generate TYPO3 HTML Documentation from rst files.
 4.DESCRIPTION
 5    Runs docker to generate TYPO3 documentation.
 6.PARAMETER SourcePath
 7    The path to the Documentation folder - uses current directory if none given.
 8.PARAMETER TargetPath
 9    The output path (will be created if it does not exist). Uses "Documentation-GENERATED-temp"
10    as fallback.
11.PARAMETER Latex
12    Disables/Enables Latex output.
13.PARAMETER SingleHtml
14    Disables/Enables generation of single HTML file.
15.PARAMETER Cache
16    Removes and recreates target path before running if 0 is given. Default: 1
17.PARAMETER Help
18    Show help for this command.
19.EXAMPLE
20    C:\PS> Generate-TYPO3-Documentation -SingleHtml 1 -Cache 0
21.NOTES
22    Author: Susanne Moog
23    Date:   August 28, 2019
24#>
25Function Generate-TYPO3-Documentation(
26    [String]
27    $SourcePath,
28    [String]
29    $TargetPath,
30    [Boolean]
31    $Latex ,
32    [Boolean]
33    $SingleHtml,
34    [Boolean]
35    $Cache = 1,
36    [Switch]
37    $Help
38) {
39    if ($Help) {
40        Get-Help $($MYINVOCATION.InvocationName)
41    }
42    else {
43        if ([String]::IsNullOrEmpty($SourcePath)) {
44            $SourcePath = $PWD;
45        }
46
47        if ([String]::IsNullOrEmpty($TargetPath)) {
48            $TargetPath = "$($PWD)\Documentation-GENERATED-temp\"
49        }
50
51        If ($Cache -And (test-path $TargetPath)) {
52            Remove-Item -Recurse -Force $TargetPath
53        }
54
55        If (!(test-path $TargetPath)) {
56            New-Item -ItemType Directory -Force -Path $TargetPath
57        }
58
59        $cmd = "docker run --rm -v $($SourcePath):/PROJECT/:ro -v $($TargetPath):/RESULT/ " +
60        "t3docs/render-documentation makehtml -c make_latex $([int]$Latex)" +
61        " -c make_singlehtml $([int]$SingleHtml);"
62
63        Invoke-Expression $cmd
64    }
65}

Linux version

The script was coded to achieve something like this:

#01 cd ~/Repositories/github.com/TYPO3-Documentation/TYPO3CMS-Reference-Typoscript
#02
#03 docker run \
#04   --rm \
#05   --user=$(id -u):$(id -g) \
#06   -v $PWD:/PROJECT/:ro
#07   -v $PWD/Documentation-GENERATED-temp/:/RESULT/ \
#08   t3docs/render-documentation \
#09   makehtml \
#10   -c make_latex 0 \
#11   -c make_singlehtml 0

which expands to:

#01 cd ~/Repositories/github.com/TYPO3-Documentation/TYPO3CMS-Reference-Typoscript
#02
#03 docker run \
#04   --rm \
#05   --user=1000:1000 \
#06   -v /home/marble/Repositories/github.com/TYPO3-Documentation/TYPO3CMS-Reference-Typoscript:/PROJECT/:ro
#07   -v /home/marble/Repositories/github.com/TYPO3-Documentation/TYPO3CMS-Reference-Typoscript/Documentation-GENERATED-temp/:/RESULT/ \
#08   t3docs/render-documentation \
#09   makehtml \
#10   -c make_latex 0 \
#11   -c make_singlehtml 0

What the lines mean:

#01

Go to the top folder of your project (not the project/Documentation subfolder.

#03

Run Docker from the commandline with run action.

#04

--rm: Remove the container (= writable copy of the read-only image) right after it has finished. Otherwise each run leaves a copy.

#05

--user: Set user permissions. Otherwise all generated files would be own by the superuser.

#06

-v: Read-only volume mapping to the project. Must be the complete and absolute path.

#07

-v: Writable volume mapping to the result folder, usually Documentation-GENERATED-temp.

#08

The container that is to be run.

#09

Action makehtml tells the container what it should do.

#10

Pass option make_latex=0 to the toolchain that the container will run.

#11

Pass option make_singlehtml=0 to the toolchain that the container will run.