Explainer - a simple program for explaining things

Rational: Why was this tool created?

Does the world really need another static site generator? Probably not, but here we go...

As a developer, I wanted to document/discuss the flow of information in the system, showing multiple plantuml diagrams and swagger endpoints in a single easy to review/update/discuss document.

Why would you use it?

To create and share some documenation about how something works. You can explain something using html directly - but explainer provides more content types (ie. plantuml, dot, markdown.) Since Explainer is fairly simple, a clojure developer can adapt it to unforseen needs.

There are other more complicated systems out there for generating html pages, asciidoctor looked cool, but also complicated. Also consider Clerk

How does it work?

Explainer reads edn files and transforms them into html files. Each edn file is a list of content of various types called chunks.

You create an input file (ie index.edn) EDN data format, then execute the 'explainer' program. It walks through each chunk of the input file and produces html for each section.

For plantUML sections, the plantUML api is invoked and the diagram is generated. See https://plantuml.com/ The easy way to create a plantuml diagram is to find a good diagram on the plantuml site, then click on it. You can then develop the diagram in the cloud, and when finished copy the text into explainer

For example, 1. use this as the 'input/index.edn' file,

[ 
      ;; chunk type       chunk-data
      :html-hiccup        [:div [:h3 "Authentication Example" ] [:br] [:br] ] 
      :plantuml-file      "diagram.pu"
]

2. place the file diagram.pu into "input/diagram.pu".

3. run "explainer" and it will generate following output (into docs/index.html, docs/diagram.png);