Aoc 2019: ONE: Docs-as-Code

29 November 2019

Docs-as-Code is the approach where you treat your documentation as code which means you store it along with your code and you "compile" it from a plain text format to HTML.

Within this repository, you can give this approach a try. Whenever you store a README.adoc along with your code, the build will pick it up and render it on the website.

To give it a try on your local machine, just execute

./gradlew  generateIndex bake bakePreview

and the build will generate the website and start a server for you. You can also get a powerful preview of your docs if you install the AsciiDoc plugin for your favourite Editor or IDE.

Example

As an example, the README.adoc for the JavaScript "Hello World" example created by docToolchain looks like this:

/day00/groovy/docToolchain/README.adoc

== Hello World

This solution is written in Groovy.

I will use my helper to read the input from a file:

[source, groovy, numbered]
....
include::solution.groovy[tags=helper]
....

=== First Star

The solutions shall print out a greeting.
I will wrap this in a simple `helloWorld` method.

[source, groovy, numbered]
....
include::solution.groovy[tags=starOne,!starTwo]
....

<1> this is where I call the helper method to read my input

[plantuml]
----
file input.txt
component readInput
component helloWorld
helloWorld -> readInput : calls
readInput -> input.txt : reads file
----

=== Second Star

There is no second star.

and it is rendered on the webpage.

About AsciiDoc

The .adoc format is just plain text but quite powerful. Here are some examples:

Headlines

Just add some = in front of your line to get a headline

== Level 1
=== Level 2
==== Level 3

Level 1

Level 2

Level 3

Basic Formatting

There are several text formatting styles available. Here are three examples:

This is *bold*, _kursive_, `monospaced`

This is bold, kursive, monospaced

Include Source

You don’t have to copy & paste your source to your docs, just reference them:

[source, groovy, numbered]
----
Unresolved directive in <stdin> - include::helloWorld.groovy[]
----

println "*"*20
println "Hello World".center(20)
println "*"*20

Diagrams

And you even have plantUML at hand - a powerful library which converts text into diagrams:

[plantuml]
----
[a] -> [b]
[b] -> [c]
[c] -> [a]
----

You can read more about AsciiDoc in the the AsciiDoc User Manual and more about the Docs-as-Code approach at https://docs-as-co.de

Now try to document your solution with your own README.adoc!