midScribe Documentation Guide

Last modified 05 Dec 2024 09:23 +01:00
Integral documentation feature
This page describes configuration of Integral documentation midPoint feature. Please see the feature page for more details.

This document provides a guide on how to prepare and maintain documentation inside XML files with midPoint objects to be able to generate documentation using midScribe.

Documentation structure

Documentation is generated using velocity templates located template directory in midscribe-core module.

Basic structure of the documentation is defined in documentation.vm template. Main template contains sections for introduction, documentation of different types of objects and conclusion. Each section is defined in a separate velocity template file. For each object type that is being documented there is a summary table in the beginning following by detailed description of the objects. Currently supported objects that can be documented are: template, resources, libraries, orgs, roles, tasks, users.

Each velocity template can be overridden using -t option and passing ZIP file containing custom template files.

Documentation header

Documentation header si defined directly in documentation.vm. Properties are used to define project name, author, version and date:

  • project.name

  • project.author

  • project.version

  • project.date

Introduction

Introduction renders a project description loaded from property project.description.

Objects

For each object description and documentation elements are used. documentation element can contain asciidoc markup.

Object templates

Object template details are defined in template.vm template.

Description contains:

  • Include references

  • Iterator specification

  • Items

  • Mappings

Resources

Resource details are defined in resource.vm template.

Description contains:

  • Referenced connector details

  • Connector configuration

  • Results handlers configuration

  • Capabilities (native, configured)

  • Object types

    • Attributes

    • Credentials

    • Activation

    • Association

  • Synchronization

    • Synchronization sorter

Libraries

Library details are defined in library.vm template.

Description contains:

  • Functions (parameters, types, return type)

Organizations

Currently only description and documentation elements are used.

Roles

Currently only description and documentation elements are used.

Tasks

Currently only description and documentation elements are used.

Users

Currently only description and documentation elements are used.

Conclusion

Empty section as a placeholder.

Rules for writing documentation

Documentation elements

Documentation should be generally written in <documentation> elements. <description> element is used to provide additional description for embedding object, mostly used in midPoint GUI.

Documentation can contain Asciidoc markup, which will be processed and rendered in the final documentation. If documentation is multi-line, it should start on a new line, all lines should be indented with same indentation as the first line.

Incorrect multi-line documentation
<resource>
    ...
    <documentation>This is a multi-line documentation.
        It starts on a new line and all lines are indented with the same
indentation as the first line.
    </documentation>
    ...
</resource>
Correct multi-line documentation
<resource>
    ...
    <documentation>
        This is a multi-line documentation.
        It starts on a new line and all lines are indented with the same indentation as the first line.

        [cols=2, options="header"]
        |===
        | Command-line options
        | Description
        | `-h, --help`
        | Print this help
        |===
    </documentation>
    ...
</resource>

Naming

While midPoint objects have mandatory names, it is also necessary to provide names for smaller parts of the configuration. For example, when documenting a resource, it is necessary to provide names objectTypes and mappings.

Naming elements for different parts of configuration are often also marked as natural keys in schema. MidPoint Studio plugin will warn about missing natural keys in the configuration. Most often these names are provided in <name> or identifier elements.

Usage options

Xml files can be sourced using the -s, --source option. This option can be used multiple times to specify multiple source directories or files.

Second set of xml files can be specified using the -as, --additional-source option. These objects won’t be directly used to create documentation, but they can be used to read additional data like reference names or descriptions. For example when documenting resource, description of connector configuration properties can be read from the connector schema.

Command also supports include -i, --include and exclude -e, --exclude patterns to filter files.

If files contains parameters that should be expanded before documentation is generated, then -p, --properties option can be used to specify properties file with parameters for expansion.

Currently supported formats are Asciidoc, PDF and HTML.

Full usage
Usage: java [-Dlogback.configurationFile=logback.xml] -jar midscribe.jar [options] [command] [command options]
  Options:
    -h, --help
      Print this help
    -s, --silent
      No output at all
      Default: false
    -v, --verbose
      Verbose output
      Default: false
    -V, --version
      Version and build description
      Default: false
  Commands:
    generate      Generate documentation
      Usage: generate [options]
        Options:
          -as, --additional-source
            Additional source directories/files, not directly used to create documentation. E.g. objects referenced in source files.
          -e, --exclude
            Exclude pattern to be used on source directories/files.
          -i, --include
            Include pattern to be used on source directories/files
          -o, --output
            Output file name (path).
          -of, --output-format
            Output format.
            Default: ADOC
            Possible Values: [ADOC, PDF, HTML]
          -p, --properties
            Properties file with parameters for report.
        * -s, --source
            Source directories/files.
          -t, --template
            Template file. File should be ZIP archive containing "template" directory with Velocity templates. Main template is "documentation.vm".
Was this page helpful?
YES NO
Thanks for your feedback