Sophora Schema Docs Administration

Overview

Sophora Schema Docs can primarily run in two distinct modes:

• Dynamic Mode - In Dynamic Mode, the app will run indefinitely. It will start an embedded Tomcat server that delivers the frontend interface at http://localhost:8080/... This mode is useful when the displayed documentation should always reflect the current state of the repository.
• Static Mode - In Static Mode, the app will only generate static files, then exits. The files can be placed on any regular web server, such as nginx or Apache.

Requirements

Sophora Schema Docs requires Java 11 or higher. It also depends on Sophora 4 or higher.

Installing and Running

Sophora Schema Docs consists of a single JAR file. Run the following command:

java -jar JARFILE --help

to get a list of all command line options:

usage: schemadoc --dynamic|--static [OPTION...]
 -d,--dynamic        Run in dynamic mode to start a web server
 -h,--help           Print this help
 -o,--out <FOLDER>   Output folder to write generated HTML files (required
                     for static mode)
 -s,--static         Run in static mode to generate HTML files

Dynamic Mode

Run the following command:

java -jar JARFILE --dynamic

to start the embedded Tomcat server at http://localhost:8080/...

The configuration file application.yaml must be placed in the current working directory.

Static Mode

Run the following command:

java -jar JARFILE --static --out FOLDER

to generate static files in FOLDER. The files can then be placed on any regular web server, such as nginx or Apache.

The configuration file application.yaml must be placed in the current working directory.

Using Docker

You can use the following command to run Sophora Schema Docs as a Docker container. Replace <OPTIONS> with appropriate command line options.

docker run \
  -p 8080:8080 \
  --mount "type=bind,source=$(pwd)/application.yaml,target=/application.yaml" \
  docker.subshell.com/sophora/schemadoc:latest \
  <OPTIONS>

Configuration

Before Sophora Schema Docs can be run, it needs to be configured. The following is an example application.yaml configuration file:

# Settings for the Sophora server connection.
sophora:
  client:
    server-connection:
      urls: https://sophora.example.com:1196
      username: user
      password: pass

# Settings for Sophora Schema Docs.
schema-doc:
  # Settings for the repository.
  repository:
    # A descriptive label for the repository.
    label: Example Repository

  # (optional) Whether to include detailed information for scripts in the documentation.
  # (default: false)
  detailed-scripts: true

  # (optional) Settings for nodetypes.
  nodetypes:
    # Settings for the 'example-nt:article' nodetype.
    # Note: Nodetype names must be enclosed in square brackets.
    '[example-nt:article]':
      # (optional) Path to a SVG icon file for this nodetype.
      # Note: The path must begin with 'icons/'
      icon-path: icons/article.svg

      # (optional) The Sophora ID of an example document for this nodetype.
      # This document will be displayed in the documentation.
      example-document: article-100

  # (optional) Settings for field types.
  field-types:
    # Settings for the 'com.example.ExampleInputField' field type.
    # Note: Field type names must be enclosed in square brackets.
    '[com.example.ExampleInputField]':
      # (optional) A descriptive label for this field type in German.
      label.de: Beispielfeld

      # (optional) A descriptive label for this field type in English.
      label.en: Example Field