<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>midScribe Documentation Guide
|
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.
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
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".Compliance
This feature is related to the following compliance frameworks:
Was this page helpful?
YES
NO
Thanks for your feedback