Documentation Generator

Generates documentation based upon a yaml- or JSON-file. Describe how your database looks, in a single file (or files) and then generate the corresponding documentation.

This document covers:

• Idea of the documentaion generator
• Documentation structure
• Destinations
• Table formats
• Usage
• Documentation types
  • Types supported
• Demos

Badges

---

Idea of the Documentation Generator

The basic idea of the Documentation Generator is one place to have a single model and then generate and distribute documentation into different places.

Each Generator generates something and a Destination can send the output to somewhere.

Some generators are supplied in-the-box, but you're able to design your own generator and destinations.

The generators acts as plugin - Just implement GeneratorConfiguration.

---
title: Basic idea
---
flowchart TD
  docFile["documentation file"]  
  docgen["Documentation Generator"]
  generator1["Generator 1"]
  generator1Generate[[Generates SQL-scripts]]
  destination1["Destination 1"]
  database[(Database)]
  
  generator2["Generator 2"]
  destination2["Destination 2"]
  markdown(["Markdown"])
  
  generator3["Generator 3"]
  destination3["Destination 3"]
  confluence(["Confluence"])
  
  generator4["Generator 4"]
  destination4["Destination 4"]
  csv(["CSV file"])
  
  generator5["Generator 5"]
  destination5["Destination 5"]
  excel(["Excel workbook"])
  
  generatorX["Generator X"]
  destinationX["Destination X"]
  something(["Something else"])

  docFile --> docgen
  docgen --> generator1
  docgen --> generator2
  docgen --> generator3
  docgen --> generator4
  docgen --> generator5
  docgen --> generatorX
  
  generator1 --> generator1Generate
  generator1Generate --> destination1
  destination1 --> database
  
  generator2 --> destination2
  destination2 --> markdown
  
  generator3 --> destination3
  destination3 --> confluence
  
  generator4 --> destination4
  destination4 --> csv
  
  generator5 --> destination5
  destination5 --> excel
  
  generatorX --> destinationX
  destinationX --> something

Loading

---

Documentation structure

The documentation file or files can be yaml- or json-files.

If you in the beginning of your file add a reference to the schema, so your IDE can validate and have code completion.

$schema:  https://patrickfust.github.io/documentation-generator/v4/documentation-schema.json

Example of a documentation file:

$schema:  https://patrickfust.github.io/documentation-generator/v4/documentation-schema.json
documentationTitle: My database
schemaName: theSchema
tables:
  - name: table_a
    createTableScript: create_table_a.sql
    fields:
      - name: field_a
        dataType: int
        foreignKey:
          tableName: table_b
          columnName: field_b
          onDelete: cascade
  - name: table_b
    fields:
      - name: field_b
        dataType: int
  - name: table_in_group
    fields:
      - name: field_b
        dataType: int

or as JSON:

{
    "$schema": "https://patrickfust.github.io/documentation-generator/v4/documentation-schema.json",
    "documentationTitle": "My database",
    "schemaName": "theSchema",
    "tables": [
        {
            "name": "table_a",
            "createTableScript": "create_table_a.sql",
            "fields": [
                {
                    "name": "field_a",
                    "dataType": "int",
                    "foreignKey": {
                        "tableName": "table_b",
                        "columnName": "field_b"
                    }
                }
            ]
        },
        {
            "name": "table_b",
            "fields": [
                {
                    "name": "field_b",
                    "dataType": "int"
                }
            ]
        },
        {
            "name": "table_in_group",
            "fields": [
                {
                    "name": "field_b",
                    "dataType": "int"
                }
            ]
        }
    ]
}

Generator Configuration File

You can either configure your Gradle directly, or have a configuration file. The configuration file is the only way to use the Maven plugin

See an example in the demo where generator-configuration.yml is located.

The generator configuration file contains a list of configurations. Each configuration consist of the class name of the configuration class and then it's fields. You can have nested objects, you just have to specify which class name it is.

Example of configuration file

- className: dk.fust.docgen.erdiagram.ERDiagramConfiguration
  documentationFile: documentation.yaml
  umlGenerator: MERMAID
  generateKeys:
    - className: dk.fust.docgen.erdiagram.GenerateKey
      destinationKey: MODEL_MERMAID_PLACEHOLDER
    - className: dk.fust.docgen.erdiagram.GenerateKey
      destinationKey: MODEL_MERMAID_GROUP_PLACEHOLDER
      filterTags: my_group
  destination:
    className: dk.fust.docgen.destination.MarkdownDestination
    file: README.md
- className: dk.fust.docgen.erdiagram.ERDiagramConfiguration
  documentationFile: documentation.yaml
  umlGenerator : PLANTUML
  generateKeys:
    - className: dk.fust.docgen.erdiagram.GenerateKey
      destinationKey: MODEL_PLANTUML_PLACEHOLDER
  destination:
    className: dk.fust.docgen.destination.MarkdownDestination
    file: README.md

---

Destinations

Destination is the where Documentation Generator will send the documentation. You can implement you own if you want or use these.

DirectoryDestination

Class name: dk.fust.docgen.destination.DirectoryDestination

Sends to separate files in the directory

Setting	Type	Description	Default
directory	File	Where the files will be stored
createParentDirectories	boolean	Should the directory's parent directories be created if missing	false

FileDestination

Class name: dk.fust.docgen.destination.FileDestination

Replace an entire file with the document.

Setting	Type	Description	Default
file	File	Location of the file. Must be writeable

Base64FileDestination

Class name: dk.fust.docgen.destination.Base64FileDestination

Base64 decodes the document and replaces the entire file with binary content. Can for instance be used in conjunction with ExcelBase64TableFormatter.

Setting	Type	Description	Default
file	File	Location of the file. Must be writeable

MarkdownDestination

Class name: dk.fust.docgen.destination.MarkdownDestination

Setting	Type	Description	Default
file	File	Markdown file to be updated

In order for the MarkdownDestination being able to substitute parts of a markdown-file, you'll mark a start and an end placeholder, and everything in between will be substituted.

Markup in Markdown

For instance this shows a substitution with the key MY_KEY, where the beginning and end is. Everything in between will be substituted.

[//]: #MY_KEY_START ()
... this is replaced ...
[//]: #MY_KEY_END ()

ConfluenceDestination

Class name: dk.fust.docgen.confluence.destination.ConfluenceDestination

In order to use Confluence as destination, you'll need to add the extension documentation-generator-confluence.

Read the documentation here

---

Table format

Some generators use tables and needs a formatter to create a string representation of the table. The table formatter you want to use, is configured when you configure the generator.

Example

- className: dk.fust.docgen.datadict.DataDictionaryConfiguration
  documentationFile: data-dictionary.yml
  tableFormatter:
    className: dk.fust.docgen.csv.format.table.CSVTableFormatter
  destination:
    className: dk.fust.docgen.destination.FileDestination
    file: data_dictionary-output.csv

MarkdownTableFormatter

Class name: dk.fust.docgen.format.table.MarkdownTableFormatter

Default table formatter for most generators.

Generates the table in a format that can be used i Markdown files.

Use it together with MarkdownDestination.

HTMLTableFormatter

Class name: 'dk.fust.docgen.format.table.HTMLTableFormatter'

Setting	Type	Description	Default
dataFields	Map<String, String>	Data fields to be appended to the table
columnWidths	List	Setting column withs

Example

tableFormatter:
  className: dk.fust.docgen.format.table.HTMLTableFormatter
  dataFields:
    table-width: "1800"
  columnWidths:
    - "255"
    - "328"
    - "114"
    - "115"
    - "149"
    - "242"

JsonTableFormatter

Class name: 'dk.fust.docgen.format.table.JsonTableFormatter'

Generates JSON.

Setting	Type	Description	Default
yaml	boolean	If true, it's rendered as yaml otherwise as json	false
prettyPrint	boolean	Should the json be pretty printed?	true

Example

tableFormatter:
  className: dk.fust.docgen.format.table.JsonTableFormatter
  yaml: true

CSVTableFormatter

Class name: dk.fust.docgen.csv.format.table.CSVTableFormatter

Read the documentation here

ExcelBase64TableFormatter

Class name: dk.fust.docgen.excel.format.table.ExcelBase64TableFormatter

Read the documentation here

---

Usage

You can use Documentation Generator as:

• Gradle plugin
• Maven plugin

---

Documentation types

The documentation generator support these documentation types, but you're free to create your own. Just implement dk.fust.docgen.Generator and dk.fust.docgen.GeneratorConfiguration.

Add a dependency in your buildscript with the corresponding artifact id.

Documentation types supported

Artifact id	Description
documentation-generator-data-dictionary	Generates Data Dictionary
documentation-generator-datalineage	Generates Data lineage
documentation-generator-erdiagram	Generates Entity-Relation diagrams
documentation-generator-sqlscript	Generates SQL-files

---

Demos

In the demos folder you can see examples on how to use the documentation generator.