Liquid Documentation Automatic Documentation Generation Frederick - - PowerPoint PPT Presentation

Liquid Documentation

Automatic Documentation Generation

Frederick Brumm

Potsdam University Institute for Computer Science Interdisciplinary Project

Potsdam, November 29, 2016

Outline

1

Introduction The Setting The Problem Liquid Documentation – The Idea and Vision

2

Liquid Documentation docgen – The Framework docgen-configkey – The Implementation docgen-maven-plugin – The Maven Plugin wordgen – The Word Generator

3

Conclusion

Frederick Brumm (Potsdam University) Liquid Documentation Frame 2 of 19

Introduction

Outline

1

Introduction The Setting The Problem Liquid Documentation – The Idea and Vision

2

Liquid Documentation docgen – The Framework docgen-configkey – The Implementation docgen-maven-plugin – The Maven Plugin wordgen – The Word Generator

3

Conclusion

Frederick Brumm (Potsdam University) Liquid Documentation Frame 3 of 19

Introduction The Setting

The Setting

Project Partner: Capgemini Deutschland GmbH develop large software system for a leading German automotive manufacturer still evolving many different documents are required for each release most of them are written by hand in programs like MS Word, Excel

Frederick Brumm (Potsdam University) Liquid Documentation Frame 4 of 19

Introduction The Problem

The Problem

writing of documents consumes time documentation lags behind the software updates have to be done manually lack of correctness

Frederick Brumm (Potsdam University) Liquid Documentation Frame 5 of 19

Introduction Liquid Documentation – The Idea and Vision

Liquid Documentation – The Idea and Vision

Source code is always the best documentation of itself! Idea: automatically generate as much parts of documents as possible

without creating descriptive content

move writing of documentation into source code update documents while building process (CI integration) Vision: more accuracy because of automatic generation developer are more likely to change documentation, if it is in source code

Frederick Brumm (Potsdam University) Liquid Documentation Frame 6 of 19

Liquid Documentation

Outline

1

Introduction The Setting The Problem Liquid Documentation – The Idea and Vision

2

Liquid Documentation docgen – The Framework docgen-configkey – The Implementation docgen-maven-plugin – The Maven Plugin wordgen – The Word Generator

3

Conclusion

Frederick Brumm (Potsdam University) Liquid Documentation Frame 7 of 19

Liquid Documentation docgen – The Framework

docgen – The Framework

Generation process in 4 phases:

1 Data Collection

no input collects the data multiple collectors in parallel

2 Aggregation

input: data from Data Collector or

• ther Aggregator

aggregate, join, prepare data multiple Aggregator in a row

3 Generation 4 Postprocessing

Frederick Brumm (Potsdam University) Liquid Documentation Frame 8 of 19

Liquid Documentation docgen – The Framework

docgen – The Framework

Generation process in 4 phases:

1 Data Collection 2 Aggregation 3 Generation

input: aggregated data generates output files

4 Postprocessing

input: list of generated files postprocesses data, e.g. upload, create wiki pages

Frederick Brumm (Potsdam University) Liquid Documentation Frame 9 of 19

Liquid Documentation docgen – The Framework

docgen – The Framework

implemented in Java interface for each phase framework controls execution of phases

Frederick Brumm (Potsdam University) Liquid Documentation Frame 10 of 19

Liquid Documentation docgen-configkey – The Implementation

docgen-configkey – The Implementation

Implementation for one example: documentation of all configuration parameter (configkey) of the software system configkeys are defined in Enums with Annotations:

public enum SampleConfigKey1 implements ConfigKey { @ValueType(defaultValue = "true", mandatory = BooleanEnum.FALSE , serializeClass = Boolean.class) @I18nText(de = "Eine kurze Beschreibung des Parameters in Deutsch.", en = "A short description of this parameter in english.") CONFIGURATION_PARAMETER }

further documentation is done in a MS Word document

Frederick Brumm (Potsdam University) Liquid Documentation Frame 11 of 19

Liquid Documentation docgen-configkey – The Implementation

docgen-configkey – The Implementation

New conventions for configkeys:

/** * A long and detailed desciption of the parameter and what it is * responsible for. You can also use the @longDescription tag * instead and use <b>simple HTML </b> in here , too. * * @values * A detailed description of all possible values and their impact. * * @recommendation * Some recommendations that should be followed (maybe some tips for * usage of this parameter). */ @Category({ CategoryEnum.CATEGORY1 , CategoryEnum.CATEGORY2 }) @ValueType(defaultValue = "true", mandatory = BooleanEnum.FALSE , serializeClass = Boolean.class) @I18nText(de = "Eine kurze Beschreibung des Parameters in Deutsch.", en = "A short description of this parameter in english.") CONFIGURATION_PARAMETER

Frederick Brumm (Potsdam University) Liquid Documentation Frame 12 of 19

Liquid Documentation docgen-configkey – The Implementation

docgen-configkey – The Implementation

Implementation: 2 Data Collector:

JavaDoc: from source code using qdox Annotation: from binary files using ASM

2 Aggregator:

joining JavaDoc and Annotation data merging multiple lists of configkey data (for maven plugin)

3 Generator:

HTML MS Word Document using wordgen Confluence wiki pages

1 Postprocessor:

creating or changing of Confluence wiki pages

Frederick Brumm (Potsdam University) Liquid Documentation Frame 13 of 19

Liquid Documentation docgen-maven-plugin – The Maven Plugin

docgen-maven-plugin – The Maven Plugin

Maven plugin to include the documentation generation into a maven building process: goal for each phase supports multiple maven projects aggregation is split up into 2 phases:

Project Aggregation: for each project separately Multi Project Aggregation: for all projects at once

configuration of all phases completely in pom files

Frederick Brumm (Potsdam University) Liquid Documentation Frame 14 of 19

Liquid Documentation docgen-maven-plugin – The Maven Plugin

docgen-maven-plugin – The Maven Plugin

docgen-maven-plugin for configkeys

Frederick Brumm (Potsdam University) Liquid Documentation Frame 15 of 19

Liquid Documentation wordgen – The Word Generator

wordgen – The Word Generator

Generates MS Word documents: takes an Word document containing content controls (CC) as template file tag of CC defines its handler:

wordgen:[handlertag]:[argument 1]:...:[ argument n]

wordgen replaces content of a CC according to its handler content is provided in wordprocessingML no dependencies to docgen, can be used separately

Frederick Brumm (Potsdam University) Liquid Documentation Frame 16 of 19

Liquid Documentation wordgen – The Word Generator

wordgen – The Word Generator

4 Provided handler: Simple replacement of all content in the CC with a new paragraph containing the provided text. Similar to above but converts HTML in the provided text using

Html2DocxConverter.

Generates new content using templates with freemarker. Handles styling templates for ordered and unordered lists.

Html2DocxConverter:

converts text containing simple HTML tags to wordprocessingML supported tags: b, i, u, p, br, code, ul, ol, li

Frederick Brumm (Potsdam University) Liquid Documentation Frame 17 of 19

Conclusion

Outline

1

Introduction The Setting The Problem Liquid Documentation – The Idea and Vision

2

Liquid Documentation docgen – The Framework docgen-configkey – The Implementation docgen-maven-plugin – The Maven Plugin wordgen – The Word Generator

3

Conclusion

Frederick Brumm (Potsdam University) Liquid Documentation Frame 18 of 19

Conclusion Conclusion

Conclusion

docgen provides a framework for automatic documentation generation example implementation for configkeys

extracts data from source and binary code generates MS Word, HTML and wiki pages will be used for production in future

can be included in a CI environment (maven plugin) MS Word documents can be generated (wordgen)

Frederick Brumm (Potsdam University) Liquid Documentation Frame 19 of 19