Description: Repository to store, contribute and showcase team documenation

Deployed URL: https://pseudo-su.github.io/doctool-template/index.html

This template pulls together various tools to make maintaining and publishing documentation from a single source controlled repository easier.

• Asciidoc - for templating more info

• OpenAPI (swagger) - for API documenation more info

• PlantUML - for diagrams more info

• MxModel - for draw.io style diagrams examples

• Pygments - Syntax highlighting supported languages

The main goal of this project is to have as much documenation as possible tracked in a single version control system.

1. Build

   # Build the builder
   $ docker build -t doctool-builder ./builder
   # Clean docs/
   $ ./clean.sh
   # Build docs/
   $ ./build.sh

2. View

   $ open docs/index.html

This project looks at all files in the resources/ folder and generates corresponding files in the docs/ folder depending on the filename suffix.

• *.adoc generates:

  • *.html

• *.openapi.yml (v3) generates:

  • *.openapi.redoc.html

• *.swagger.yml (v2) generates:

  • *.swagger.redoc.html

  • *.swagger.doc.html

• *.mxgraph.xml generates:

  • *.mxgraph.html

• investigate switching to asciidoctor.js [ diagrams’s | pdf’s | source syntax highlighting]

• Investigate better replacement for ./build-single-mxgraph.sh that can actually export images

• Publish the docker container instead of storing definition in ./builder/