Oxygen Documentation Action

This action triggers Oxygen Scripting to generate documentation for schema files on your repository. It works with XML Schema (XSD), XSL, WSDL, JSON Schema and OpenAPI files. All you have to do is to include this action in your workflow and choose the schema to document. Find more info about workflows on https://docs.github.com/en/actions/using-workflows.

👀 See Oxygen Scripting for more details about this script, and other useful tools.

Requirements

In order to use this action, you need to obtain an Oxygen Scripting license key from https://www.oxygenxml.com/xml_scripting/pricing.html (you can also request a trial). Add it as a secret to your repository (Settings → Secrets → Actions → New repository secret), and name it "SCRIPTING_LICENSE_KEY". Then use it as an environment variable:

env:
  SCRIPTING_LICENSE_KEY: ${{secrets.SCRIPTING_LICENSE_KEY}}

Sample usage

If you don't already have a workflow defined in your repository, you can use one of the samples below.

💡 This workflow requires manual trigger from the 'Actions' tab:

name: Run Documentation Script
on:
  workflow_dispatch:
    inputs:
      schemaFile:
        description: 'Schema file to generate documentation for.'
        required: true # e.g. resources/schema.xsd
jobs:
  generate-doc:
    runs-on: ubuntu-latest
    steps:
      - name: Oxygen Documentation Script
        uses: oxygenxml/oxygen-script-documentation-action@v1.0.0
        env:
          SCRIPTING_LICENSE_KEY: ${{secrets.SCRIPTING_LICENSE_KEY}}
        with:
          schemaFile: ${{ inputs.schemaFile }}

💡 This workflow starts whenever an XSD file is changed, and runs the Documentation Script for the main XSD file.

name: Run Documentation Script (for XSD files)
on:
  push:
    branches:
      - main
    paths:
      - '**.xsd'
jobs:
  generate-doc:
    runs-on: ubuntu-latest
    steps:
      - name: Oxygen Documentation Script
        uses: oxygenxml/oxygen-script-documentation-action@v1.0.0
        env:
          SCRIPTING_LICENSE_KEY: ${{secrets.SCRIPTING_LICENSE_KEY}}
        with:
          schemaFile: schemas/main.xsd

👀 Check Oxygen Scripting - Documentation template for a ready-to-use template with some sample schema files.

Deployment to GitHub Pages

After a successful run of the Documentation Script, the documentation files are pushed to the gh-pages branch. If you want the documentation to be published to GitHub Pages, all you have to do is go to Settings → Pages, and under Build and deployment section select the gh-pages branch instead of the main branch.

The deployment workflow should automatically start and the documentation should be available shortly at: https://{userid}.github.io/{reponame}/{schemaFile}.html.