Tutorial: add docToolchain as submodule

Unresolved directive in tutorial2.adoc - include::feedback.adoc[]

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

curl -o src/docs/test.adoc https://gist.githubusercontent.com/mojavelinux/4402636/raw/b8b02adc3c0ddb92df505ba3eb8e625952615b7a/test.asciidoc.txt

and since this great test document includes another document, let’s fetch this also

curl -o src/docs/include.asciidoc.txt https://gist.githubusercontent.com/mojavelinux/4402636/raw/b8b02adc3c0ddb92df505ba3eb8e625952615b7a/include.asciidoc.txt

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
./gradlew -p .. wrapper
This will use the gradle wrapper contained in docToolchain to initialize your main project
and it will also install the wrapper to that you don't need to install gradle by yourself.

Alternatively use sdkman

INFO: if you need to configure proxies and repository caches (artifactory) for Gradle to fetch external dependencies, please take a look at this blog post: Behind the great Firewall

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
use https and not the ssh to clone the submodule. This enables anonymous clones.

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:

./gradlew tasks
FAILURE: Build failed with an exception.
* Where:
Script '/home/docToolchain/tutorial1/docToolchain/scripts/AsciiDocBasics.gradle' line: 25
* What went wrong:
A problem occurred evaluating script.
> ./Config.groovy (No such file or directory)

That’s correct — docToolchain needs a configuration file!

Let’s create an empty one and see how this works:

bash
    touch Config.groovy
    ./gradlew tasks

et voilá, you get a list of all available tasks:

bash
> Task :tasks

------------------------------------------------------------
All tasks runnable from root project
------------------------------------------------------------

Build tasks
-----------

...

DocToolchain tasks
------------------
convertToDocx - converts file to .docx via pandoc. Needs pandoc installed.
convertToEpub - converts file to .epub via pandoc. Needs pandoc installed.
exportChangeLog - exports the change log from a git subpath
exportContributors - exports all contributors for all asciidoc files
exportEA - exports all diagrams and some texts from EA files
exportExcel - exports all excelsheets to csv and AsciiDoc
exportJiraIssues - exports all jira issues from a given search
exportMarkdown - exports all markdown files to AsciiDoc
exportPPT - exports all slides and some texts from PPT files
exportVisio - exports all diagrams and notes from visio files
generateDeck - use revealJs as asciidoc backend to create a presentation
generateDocbook - use docbook as asciidoc backend
generateHTML - use html5 as asciidoc backend
generatePDF - use pdf as asciidoc backend
publishToConfluence - publishes the HTML rendered output to confluence

Documentation tasks
-------------------
asciidoctor - Converts AsciiDoc files and copies the output files and related resources to the build directory.
groovydoc - Generates Groovydoc API documentation for the main source code.
javadoc - Generates Javadoc API documentation for the main source code.

...

To see all tasks and more detail, run gradle tasks --all

To see more detail about a task, run gradle help --task <task>

BUILD SUCCESSFUL in 40s
1 actionable task: 1 executed
~/tutorial1$

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))

build.gradle
//configure docToolchain to use the main project's config
project('docToolchain') {                                   (1)
    if (project.hasProperty('docDir')) {                    (2)
        docDir = '../.'                                     (4)
        mainConfigFile = 'Config.groovy'                    (5)
    } else {
        println "="*80                                      (3)
        println "  please initialize the docToolchain submodule"
        println "  by executing git submodule update -i"
        println "="*80
    }
}
1 changes the scope to docToolchain as subproject
2 checks if the subproject has been initialized
3 outputs a hint if subproject has not been initialized
4 moves the base folder for docToolchain to the main project folder
5 this enables you to point docToolchain to your own config file

7. all steps within Docker

get / clone https://github.com/docToolchain/docs-as-co.de , then

cd into appropriate directory

cd docs/_pages/getstarted/tutorial2

create docker image: run

docker build --force-rm -t stephan.praetsch:doctoolchain-tutorial1 .

determine docker image id

docker images | grep doctoolchain-tutorial1 | cut -d " " -f 8

run this docker image: Which environment?

> docker run $(docker images | grep doctoolchain-tutorial1 | cut -d " " -f 8) gradle --version

------------------------------------------------------------
Gradle 3.2.1
------------------------------------------------------------

Build time:   2012-12-21 00:00:00 UTC
Revision:     none

Groovy:       2.4.8
Ant:          Apache Ant(TM) version 1.9.9 compiled on July 22 2018
JVM:          1.8.0_222 (Oracle Corporation 25.222-b10)
OS:           Linux 4.15.0-64-generic amd64

Execute doctoolchain

> docker run $(docker images | grep doctoolchain-tutorial1 | cut -d " " -f 8) gradle publishToConfluence
...
Converting /tmp/tutorial1/src/docs/test.adoc
:docToolchain:publishToConfluence

BUILD SUCCESSFUL

extract created test.html doc to local directory

docker run $(docker images | grep doctoolchain-tutorial1 | cut -d " " -f 8) cat build/docs/html5/test.html > test.html

now you can view test.html