Skip to content

Latest commit

 

History

History
120 lines (95 loc) · 3.79 KB

README.adoc

File metadata and controls

120 lines (95 loc) · 3.79 KB

midscribe

Tool that is able to generate documentation from midpoint configuration objects in asciidoc format and HTML/PDF export.

How To Build

Maven 3 is used to build this repository. To build whole project please run:

mvn clean install -DskipTests

Executable JAR file will be located in midscribe/midscribe-cmd/target/midscribe-executable.jar

Command Line Options

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:
          -ao, --adoc-output
            AsciiDoc output file
          -e, --exclude
            Exclude files
            Default: []
          -ef, --export-format
            Export format
            Possible Values: [PDF, HTML]
          -eo, --export-output
            Export output file
          -pf, --properties-file
            Properties file
            Default: midscribe.properties
          -i, --include
            Include files
            Default: []
          -s, --source-directory
            Source directory with XML files. This option can be used multiple times to define more than one directory.
          -t, --template
            Template file. File should be ZIP containing "template" directory with Velocity templates or path to directory with templates. Main template is "documentation.vm"

Examples

Following example generates only AsciiDoc file

java -jar midscribe-executable.jar generate -s <FOLDER_WITH_MIDPOINT_XML_OBJECTS> -ao documentation.adoc

This example generates AsciiDoc as well as HTML file

java -jar midscribe-executable.jar generate -s <FOLDER_WITH_MIDPOINT_XML_OBJECTS> -eo documentation.html -ef HTML

This example generates AsciiDoc as well as PDF file with custom property file

java -jar midscribe-executable.jar generate -s <FOLDER_WITH_MIDPOINT_XML_OBJECTS> -eo documentation.pdf -ef PDF -pf <CUSTOM_PROPERTY_FILE>

Supported midpoint objects

The generator supports the following midpoint objects:

  • Object templates

  • Resources

  • Libraries

  • Orgs

  • Roles

  • Tasks

  • Users

  • Archetypes

  • LookupTables

  • Notifications

  • SecurityPolicies

  • ValuePolicies

Properties File Configuration

The midscribe.properties or custom.properties file needs to include the following attributes for the title, project description etc. :

  • project.name=MidPoint Project Documentation

  • project.author=Company, s.r.o.

  • project.version=0.1

  • project.date=2025-01-16

  • project.description=This is the optional preamble (an untitled section body).\ Useful for writing simple sectionless documents consisting only of a preamble.

  • project.expressionEnabled=false (false is default, if you want to generate all expressions in the documentation you need to set it to true. Expressions are generated when there is custom script in mappings, notifications etc.)

Custom styling

You can customize you own style that will be used for generating HTML/PDF file. For that you need to override the style.css file that is located :

midscribe/midscribe-core/src/main/resources/css/style.css

When there is no default css file, AsciiDoctor default style will be used. PDF file uses the same styling as HTML because the PDF file is generated from HTML file.

Example

Here is an example generated from object located in midscribe-core/src/test/resources/objects folder.