Tutorial: add docToolchain as submodule

This short tutorial will show you how to add docToolchain as git submodule.

1. Motivation

Git submodules are references to a certain commit of another git repository.
This makes submodules perfect to include repositories — on which your own project depends — into your project without copying them.
Since a submodule is a pointer to a certain commit, it is also easy to update this pointer when a newer version is available.

2. What you’ll build

In this tutorial, you will create a simple gradle project with a single .adoc file.
To this project, you’ll add docToolchain to generate an HTML file and a PDF.

3. What you’ll need

20(?) minutes

a windows or *nix based machine

a text editor or IDE

jdk 1.8 installed

git installed

gradle installed

the commands needed to go through this tutorial will be bash based.
So if you are on a windows environment, please make sure that you start a bash
or translate the commands for yourself - I am sure this will be a no-brainer.

4. Create a simple project to start with

create a new folder and switch to it

mkdir tutorial1
cd tutorial1

init git (it’s a new project!) and create a simple folder structure for your documents

git init
mkdir src
mkdir src/docs

create a simple .adoc file.
To make it simple, just fetch one from the net via curl

The main file ./src/docs/test.adoc contains a reference to a stylesheet which is not available, so please open it in your favourite editor (vi?) and remove the reference (:stylesheet: asciidoc.css in line 17)

vi src/docs/test.adoc

Since we like Gradle projects, let’s initialize the toplevel project (tutorial1) as gradle project.
This will make docToolchain a subproject.

gradle init

and

gradle wrapper

for convenience.
That’s it!

use the wrapper, luke!

Don’t have gradle installed?

Just first add docToolchain as submodule (next step) and then do

cd docToolchain
./gradlew -p .. init

This will use the gradle wrapper contained in docToolchain to initialize your main project.

For a real project, you now would add some source code and more build instructions.
To render the document with docToolchain, we only need the document itself.

5. add docToolchain as submodule

In order to add docToolchain as submodule, you just have to execute the following command

git submodule add https://github.com/docToolchain/docToolchain.git

Tip

use https and not the ssh to clone the submodule. This enables anonymous clones.

To checkout the first release version of docToolchain, switch to the submodule and checkout the tag V1.0.0

cd docToolchain
git checkout tags/V1.0.0
cd ..

add docToolchain as sub-project to your main project by adding an include to the settings.gradle file

echo "include 'docToolchain'" >> settings.gradle

If you now list all tasks of your project, gradle will pick up the docToolchain build file from the subproject,
download all dependencies and output the list of available tasks and fail with an exception:

As you can see, you now have already a lot of documentation tasks at hand.

6. setting up the configuration

create a simple Config.groovy file to start with:

Config.groovy

outputPath = 'build/docs'// Path where the docToolchain will search for the input files.// This path is appended to the docDir property specified in gradle.properties// or in the command line, and therefore must be relative to it.
inputPath = 'src/docs'
inputFiles = [
[file: 'test.adoc', formats: ['html','pdf']],
]
taskInputsDirs = ["${inputPath}/images"]
taskInputsFiles = []

And since we want to use our main project to be the source of the documentation, we have to tell docToolchain where it can find it. Since we don’t want to touch the original docToolchain sources, we override the config via the build.gradle file.
Just add the following lines to your build.gradle.
Since we have an empty main project in this tutorial, you can even overwrite the whole build.gradle with the following lines:

(it instructs docToolchain to use the main project as starting point for all other configurations (like the one we just defined in Config.groovy))