./gradlew generateIndex bake bakePreview
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.
As an example, the README.adoc
for the JavaScript "Hello World" example created by docToolchain
looks like this:
== 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.
The .adoc
format is just plain text but quite powerful.
Here are some examples:
Just add some =
in front of your line to get a headline
== Level 1 === Level 2 ==== Level 3 |
Level 1Level 2Level 3 |
There are several text formatting styles available. Here are three examples:
This is *bold*, _kursive_, `monospaced` |
This is bold, kursive, |
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[] ---- |
|
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
!