Install docToolchain

Miranda Boerlage Ralf D. Müller Nicca3006 Jeremie Bresson Bennykillua Jérémie Bresson T8xi Michael Krauße Ralf D. Müller stehlih Dr. Stefan Pfeiffer Alexander Schwartz feinstaub Jakub J Jablonski jakubjab Jorge Dr. Gernot Starke Lars Francke

7 minutes to read

Purpose

This guide explains how to set up docToolchain in the following environments:

  • A MacOS with bash

  • Linux/WSL2 with bash

  • Windows with PowerShell

  • Windows with cmd.exe

All you need to work with docToolchain is a wrapper script taking care of everything. This wrapper:

  • Ensures that everyone using your repository uses the same docToolchain version.

  • Keeps all docToolchain technology out of your repository.

  • Wraps your commands and directs them to your local installation.

  • Checks your docToolchain installation. If not installed, the wrapper will do it for you via direct download or Docker.

Did you already work with an older version of docToolchain? Please note that the way it is installed has changed since the v2.x release.
Steps for MacOS/Linux/WSL2 with bash
If you are going to use docToolchain in different projects install the dtcw (docToolchainWrapper) for each one. docToolchain itself will only be installed once in your home folder.

If you have an Apple silicon (M1/M2) Mac, make sure that you have docker up and running type the following commands in the Terminal:

`arch -x86_64 /bin/bash`
dtcw uses bash as shell and thus tries to find Java from within bash. If you use dtcw from another shell like zsh, your shell knows about the right java version but your bash doesn’t. In that case, please switch to bash and make sure that the right java version is known. Afterwards, you can switch back to your shell.

Now, type the following:

cd <your project>
curl -Lo dtcw doctoolchain.github.io/dtcw
chmod +x dtcw

If you don’t have curl installed, you can also use wget:

cd <your project>
wget doctoolchain.github.io/dtcw
chmod +x dtcw

Since you run docToolchain without Docker, you must get the right Java-Runtime/JDK:

./dtcw getJava

Next, type the following:

./dtcw tasks --group=doctoolchain
Windows with Powershell
cd <your project>
Invoke-WebRequest doctoolchain.github.io/dtcw.ps1 -Outfile dtcw.ps1
Got an error message that you are not allowed to execute powershell scripts? Try to switch to an unrestricted powershell by executing powershell.exe -ExecutionPolicy Unrestricted.
Windows with cmd.exe
cd <your project>
curl -Lo dtcw.bat doctoolchain.github.io/dtcw.bat
dtcw.bat wraps the dtcw.ps1 script and executes it in powershell. This might be easier to use if you haven’t yet configured your powershell as a developer.
In order to support development for your project on both Linux and Windows, it makes sense to download all three dtcw scripts (.sh, .ps1 and .bat) to your project.

Let the Wrapper Use a New docToolChain Release

If you have just downloaded the wrapper, there is no need to do this. In this case, just skip to Run your First Command.

If there is a new docToolChain release you wish to use, do the following:

  1. Open the dtcw bash script (.sh, .ps1 and .bat) in your favourite text editor and look for the VERSION-line at the start of the file:

# find official release versions on github:
# https://github.com/docToolchain/docToolchain/releases
# set VERSION to "latest" to get the unreleased latest version
VERSION=2.0.5

  1. Update it to match the latest release and and everything will be updated with the next run. This will not update the wrapper (dtcw) itself. If you think you should update the wrapper, please re-install it.

  2. If you want to test a not-yet-released feature, you can set the VERSION to latest and dtcw will clone or pull the current default branch of the project. Please note this only works with a local copy, not with a Docker install.

  3. If you want to develop new features for docToolchain, you can also use latestdev as version. In this case, dtcw will try to clone the docToolChain repository with the ssh-git protocol to a fork in $HOME/.doctoolchain/docToolchain-latest.

latest and latestdev currently only work with the bash version of the wrapper.

Run your First Command

To get started with docToolchain, run tasks as the first command:

Linux / WSL2 with bash
./dtcw tasks --group=doctoolchain
Windows with Powershell
./dtcw.ps1 tasks --group=doctoolchain
Windows with cmd.exe
dtcw.bat tasks --group=doctoolchain

This command shows all docToolchain tasks and verifies that docToolchain is installed by doing the following:

  • It checks for a configuration file and creates one if it does not exist. Prefers a local installation.

  • It makes use of Docker (if available) where there is no local installation.

If this is your first time installing docToolchain, downloading might take a while.

  • If Docker is not available, it downloads and installs docToolchain to your home folder.

    • It then runs a Gradle build through the Gradle wrapper. If this is your first time, it will download and install Gradle.

    • The Gradle build also fetches some dependencies. This will also take a while if run for the first time.

If you are behind a corporate proxy, you might need to consider build-script dependencies are fetched from a repository referenced by the property mavenRepository. By default the value https://plugins.gradle.org/m2/ is used. When a repository requiring credentials is used the properties mavenUsername and mavenPassword can be set as well.
Example command passing a custom maven repository with credentials from the command line
./gradlew generateHTML -PmavenRepository=your_maven_repo -PmavenUsername=your_username -PmavenPassword=your_pw --info

You’ll notice the installation is an incremental process and will take a while because of all the additional dependencies needed. After the first few commands, you’ll have all the required dependencies installed and things will run faster.

=== Configure docToolChain to Use Existing Documents

If your project already has documents in AsciiDoc format, you’ll need to tell docToolchain where to find them.

To do so, take a look at the created docToolchainConfig.groovy and update it.

=== Create a New Project from Scratch with Arc42

If you want to use the arc42 template in your project, you can get it in AsciiDoc format by using the following commands.

If you use cmd.exe, follow the Windows instructions but replace .ps1 with .bat. 
./dtcw downloadTemplate
./dtcw.ps1 downloadTemplate

=== Generate HTML and PDF

By now, the docToolchain wrapper dtcw should be in your project folder along with the arc42 template.

Now Let’s render arc42 to HTML and PDF. To do so, run the commands below:

./dtcw generateHTML
./dtcw generatePDF
./dtcw.ps1 generateHTML
./dtcw.ps1 generatePDF

As a result, you will see the progress of your build together with some warnings which you can just ignore for the moment.

The first build generated some files within the build:

build
|-- html5
|   |-- arc42
|   |   `-- arc42.html
|   `-- images
|       |-- 05_building_blocks-EN.png
|       |-- 08-Crosscutting-Concepts-Structure-EN.png
|       `-- arc42-logo.png
`-- pdf
    |-- arc42
    |   `-- arc42.pdf
    `-- images
        |-- 05_building_blocks-EN.png
        |-- 08-Crosscutting-Concepts-Structure-EN.png
        `-- arc42-logo.png

Congratulations! If you see the same folder structure, you’ve just rendered the standard arc42 template as HTML and PDF!

Please raise an issue on github if you didn’t get the right output.

Blog-Posts: Behind the great Firewall, Enterprise AsciiDoctor