Liquid Documentation Automatic Documentation Generation Frederick Brumm Potsdam University Institute for Computer Science Interdisciplinary Project Potsdam, November 29, 2016
Outline Introduction 1 The Setting The Problem Liquid Documentation – The Idea and Vision Liquid Documentation 2 docgen – The Framework docgen-configkey – The Implementation docgen-maven-plugin – The Maven Plugin wordgen – The Word Generator Conclusion 3 Frederick Brumm (Potsdam University) Liquid Documentation Frame 2 of 19
Introduction Outline Introduction 1 The Setting The Problem Liquid Documentation – The Idea and Vision Liquid Documentation 2 docgen – The Framework docgen-configkey – The Implementation docgen-maven-plugin – The Maven Plugin wordgen – The Word Generator Conclusion 3 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 Introduction 1 The Setting The Problem Liquid Documentation – The Idea and Vision Liquid Documentation 2 docgen – The Framework docgen-configkey – The Implementation docgen-maven-plugin – The Maven Plugin wordgen – The Word Generator Conclusion 3 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 other 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 Introduction 1 The Setting The Problem Liquid Documentation – The Idea and Vision Liquid Documentation 2 docgen – The Framework docgen-configkey – The Implementation docgen-maven-plugin – The Maven Plugin wordgen – The Word Generator Conclusion 3 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
Recommend
More recommend
