7 minutes to read
Getting the Wrapper
Basically all you need to work with docToolchain is a simple wrapper script taking care of everything. (If you already worked with an older version of docToolchain please note that the way it is installed has changed since the v2.x release.)
This wrapper helps by:
Ensuring that everyone using your repository uses the same docToolchain version.
Keeping all docToolchain technology out of your repository.
Wrapping your commands and directing them to your local installation.
Checking your docToolchain installation (if not installed, the wrapper will do it for you via direct download or Docker).
This guide explains how to set up docToolchain in the following environments:
A Linux/WSL2 with bash
Windows with PowerShell
Windows with cmd.exe
Please select the appropriate setup and follow these instructions to install docToolchain step by step.
|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.|
cd <your project> curl -Lo dtcw doctoolchain.github.io/dtcw chmod +x dtcw
if you don’t have
curl installed, you can also use
cd <your project> wget doctoolchain.github.io/dtcw chmod +x dtcw
cd <your project> Invoke-WebRequest doctoolchain.github.io/dtcw.ps1 -Outfile dtcw.ps1
cd <your project> curl -Lo dtcw.bat doctoolchain.github.io/dtcw.bat
|In order to support development for your project on both, Linux and Windows, it makes sense to download all three scripts to your project.|
Configure the Wrapper
There is no need to configure the wrapper itself if you have just downloaded it. In this case, just skip to Running your First Command.
But from time to time you should check github to see if there are new releases you want to use.
In this case, open dtcw in your favourite 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
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.|
There are some situation where you want to test a not-yet-released feature.
In such a case, you can set the
pull the current default branch of the project.
This only works with a local copy, not with a docker install.
You can also use
latestdev as version.
In this case,
dtcw will try to clone the repository with the ssh-git protocoll.
This way, you can easily point it to your fork and develop new features for docToolchain.
You will find the fork in
Running your First Command
To get started with docToolchain, run
tasks as the first command:
./dtcw tasks --group=doctoolchain
./dtcw.ps1 tasks --group=doctoolchain
dtcw.bat tasks --group=doctoolchain
This command shows all docToolchain tasks and verifies that docToolchain is installed by doing the following:
Checking for a configuration file (and create one if none exist). Prefers a local installation.
Making use of Docker (if available) where there is no local installation.
|If this is your first time installing docToolchain, the images download might take a while.|
if docker is not available, it will download and install docToolchain to your home folder
it will then run a gradle build through the gradle wrapper. If this is your first time, it will download and install gradle.
the gradle build will also fetch 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
./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.
=== 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.
=== arc42 from Scratch
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
=== Building and Creating Templates.
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.
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.