ANTIDOC

in a nutshell

Olivier Jourdan <olivier.jourdan@wovalab.com>

Agenda

  1. Introduction notes

  2. Antidoc goals

  3. What you can currently get?

  4. What’s under the hood?

  5. Next steps to come

Introduction

About writing documentation

Why writing documentation?

  • to help understanding the code

    • for maintenance purpose

    • to onboard new developers on a projet

    • to share information with non developer people

  • to comply with regulation rules

What’s happening usually?

If it exists, documentation is not up to date with code, because:

  • it’s not the priority

  • it’s not easy to write

  • we hate are not very happy to write documentation

out of date documentation is often worse than no documentation

Part I

Antidoc goals

The main goals

  • Generate LabVIEW source code documentation automatically

  • Take the best out of available info:

    • explicit → project/class/lib/vi descriptions

    • implicit → communication links between the different parts of the code

  • Obtain a document in a standard file format of your choice

V1.0 and V1.1 Antidoc version goals

  • Validate the documentation generation workflow

  • Validate the capability to get valuable documentation

Part II

What you get with Antidoc v1.1

Introduction notes

  • Getting implicit content requires to analyse the code components

  • This content add lots of value to the documentation

Currently, Antidoc only supports DQMH® framework component parsing

The basic way

Antidoc GUI

  • Install Antidoc from VIPM

  • Open Antidoc tool
    from the LabVIEW tool menu

  • Generate the documentation

  • Open the generated file whith
    Chrome/Opera/Firefox using
    Asciidoctor.js Live Preview extension

Here is what you can obtain…​

This documentation is useful to…​

  • Onboard new member in your development team

  • Lead design reviews

The advanced way

  • Use the Antidoc CLI tool in your CI process

  • Render the final document threw a specific CI job

Antidoc CLI tool
Glance at this GitLab project to see a full CI configuration

Supported output format

Some examples from Antidoc users…​

Part III

What’s under the hood?

What were our challenges?

  • Find a way to offer multiple output file format

  • Concentrate development effort on documentation content rather than generating the different file format

The solution

Writing simple plain-text file…​

…​using AsciiDoc syntax.

Asciidoctor toolchain will convert AsciiDoc files to final format.

How things work

Antidoc workflow

Antidoc rely on open source projects

Antidoc is open source

You can help Antidoc project by:

  • reporting issues

  • sharing feature ideas

  • contributing to the code or documentation

Special thanks to the Antidoc contributors

Bertrand Pouteau - Cyril Gambini - Fabiola De La Cueva
Joerg Hampel - Tatiana Boyé

Part IV

Next steps to come

UML Class diagram

UML Class diagram

Other framework support

  • Actor Framework

  • JKI State Machine Objects

  • …​

More

  • Improve DQMH® framework parsing

  • Libraries filtering

  • Multi target support

  • Localized output documentation support

  • …​

Resources

Antidoc on vipm.io

Antidoc website

Antidoc project on GitLab

Antidoc YouTube Videos

Any questions?

Thank you