10 minutes to read
docToolchain is composed of two parts:
doctoolchainwhich is the toolchain used to create your documentation
the docToolchain shell wrapper script installed in your project which calls the toolchain
The use of this setup has the following advantages:
It’s easy to build your documentation within your project folder.
Ensures that everyone in the project uses the same docToolchain version.
Keeps all docToolchain technology out of your project repository.
Facilitates the installation of the docToolchain if not installed.
Makes it easier to upgrade to never versions of docToolchain.
dtcw in your project directory
The docToolchain wrapper script
dtcw.bat for MS Windows, is meant to be installed in your project root directory.
The wrapper script simplifies calls to the docToolchain.
|Even if you are going to use docToolchain in multiple projects, the toolchain will only be installed once on your system.|
If you have an Apple silicon (M1/M2) Mac, make sure that you have docker up and running and type the following commands in the Terminal:
`arch -x86_64 /bin/bash`
dtcw into your project directory and make the script executable with the following commands:
cd <your project> curl -Lo dtcw https://doctoolchain.org/dtcw chmod +x dtcw
If you don’t have
curl installed, you can also use
cd <your project> wget doctoolchain.org/dtcw chmod +x dtcw
cd <your project> Invoke-WebRequest doctoolchain.org/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
cd <your project> curl -Lo dtcw.bat doctoolchain.org/dtcw.bat
In case your development team uses different operating systems, put the wrapper scripts for the desired operating systems (
Once the docToolchain wrapper is installed in your project directory you have to decide how to install the toolchain:
docToolchain depends on Java 11 (Java 11, 14, and 17 are also supported)
If you don’t use the docToolchain container image you have to install Java on your system.
In case you have Java already installed, make sure
You may use
Run docToolchain in a container
The docToolchain project provides a container image of approximatley 900 MB from the Docker Hub container registry. The Dockerfile from which the image is created may be found at https://github.com/docToolchain/docker-image.
To to run docToolchain in a container you need an installed container engine. The best known container engine is Docker.
If the container engine is installed you can Run your First Command. The docToolchain wrapper script in your project directory will detect the container engine and pull the docToolchain image on the first invocation.
Install docToolchain with
To install docToolchain in
$HOME/.doctoolchain execute the following command.
./dtcw install doctoolchain
In case you have no Java installed you may use
dtcw to install Java in a sub-directory of
./dtcw install java
Unable to locate Java Runtime - check yout Bash environment
If you use
In case you have no Java installed you can use
dtcw.ps1 to install Java:
.\dtcw.ps1 install java
dtcw.bat install java
If the docToolchain installation finished successfully, you are ready to Run your First Command.
Install docToolchain with SDKMAN!
TODO: description how to install docToolchain with SDKMAN!.
Run your First Command
Call the docToolchain wrapper with
tasks --group doctoolchain to show all tasks provided by docToolchain.
Those tasks may be used when invoking the docToolchain wrapper script.
|The first time docToolchain is called, it downloads all necessary dependencies. Therefore the execution of the command may take some time. Subsequent calls to docToolchain will be faster.|
./dtcw tasks --group=doctoolchain dtcw 0.50 - 8061694f docToolchain 2.3.0 Available docToolchain environments: local (1) Environments with docToolchain [2.3.0]: local (2) Using environment: local (3) Using Java 17.0.6 [/home/john_doe/.doctoolchain/jdk/bin/java] (4) Downloading https://services.gradle.org/distributions/gradle-7.5.1-bin.zip (5) ..........10%..........20%..........30%...........40%..........50%..........60%..........70%...........80%..........90%..........100% Welcome to Gradle 7.5.1! Here are the highlights of this release: - Support for Java 18 - Support for building with Groovy 4 - Much more responsive continuous builds - Improved diagnostics for dependency resolution For more details see https://docs.gradle.org/7.5.1/release-notes.html To honour the JVM settings for this build a single-use Daemon process will be forked. See https://docs.gradle.org/7.5.1/userguide/gradle_daemon.html#sec:disabling_the_daemon. Daemon will be stopped at the end of the build > Configure project : Config file '/code/docToolchainConfig.groovy' does not exist' (6) [ant:input] [ant:input] do you want me to create a default one for you? (y, n) y
|1||List of available docToolchain environments. The output may vary depending on your system. In our example only the
|2||Environments in which docToolchain s available. The output may vary depending on how you installed docToolchain. In our example docToolchain was found in the user’s local environment in
|3||Shows the used docToolchain environment. In case docToolchain is installed in more than one environment the wrapper script picks the environment in the following order:
|4||Location of the used Java. In our example Java was installed in the local environment with the docToolchain wrapper script.|
|5||docToolchain was invoked the first time, thus it is downloading its dependencies.|
|6||The docToolchain configuration file
.\dtcw.ps1 tasks --group=doctoolchain
dtcw.bat tasks --group=doctoolchain
If you are behind a corporate proxy, you might need to consider build-script dependencies are fetched from a repository referenced by the property
DTC_OPTS="-PmavenRepository=your_maven_repo -PmavenUsername=your_username -PmavenPassword=your_pw" ./dtcw tasks --group=doctoolchain --info
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 Documentation 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.
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 |-- 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.
Upgrading to a New docToolchain Release
If there is a new docToolchain release you wish to use, do the following:
Open the docToolchain wrapper script (
dtcw.bat) in your favourite text editor and look for the line with
DTC_VERSIONwhich should be localted near the start of the file:
# See https://github.com/docToolchain/docToolchain/releases for available versions. # Set DTC_VERSION to "latest" to get the latest, yet unreleased docToolchain version. VERSION=2.1.0
Change it to match the desired release.
In case you want to install docToolchain in local user enviroment install the new docToolchain release with the following command:
./dtcw install doctoolchain
If you want to test a not-yet-released feature, you can set the
pullthe current default branch of the project. Please note this only works with a local copy, not with a Docker install.
If you want to develop new features for docToolchain, you can also use
latestdevas version. In this case,
dtcwwill try to clone the docToolchain repository with the ssh-git protocol to a fork in
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.