Json schema

actions/json-schema/check-docs/README.md

@@ -0,0 +1,44 @@
+# Render JSON Schema documentation
+
+This action checks that documentation for JSON Schemata is up to date.
+It uses [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) via the `render-docs` action.
+
+The action suceeds if documentation is rendered, or fails if there are differences between the in-repo docs, and re-rendering them.
+Note that the docs must be committed to the repo in order for this action to succeed.
+
+## Inputs
+
+INputs are the same as the `render-docs` action, and are passed through to that action.
+
+## `input-files`
+
+**Required**
+Path to JSON schema file or directory of files to be processed.
+See [json-schema-for-humans documentation](https://github.com/coveooss/json-schema-for-humans?tab=readme-ov-file#usage) for more details.
+
+## `outputs`
+
+**Required**
+Path to directory (or filename if rendering single file) for rendered documentation to be written..
+See [json-schema-for-humans documentation](https://github.com/coveooss/json-schema-for-humans?tab=readme-ov-file#usage) for more details.
+
+## `output-format`
+
+Default: `html`.
+Should the rendered documentation be `html` or markdown (`md`)
+
+## Outputs
+
+None
+
+## Example usage
+
+```yaml
+      - id: render-json-schema
+        uses: RMI-PACTA/actions/actions/json-schema/render-docs@main
+        with:
+          input-files: 'inst/extdata/schema'
+          outputs: 'inst/extdata/schema'
+          output-format: html
+```
+

actions/json-schema/check-docs/action.yml

@@ -0,0 +1,43 @@
+# action.yml
+name: 'Check JSON Schema Documentation'
+description: 'Check JSON Schema docs usin json-schema-for-humans'
+inputs:
+  input-files:  # id of input
+    description: 'Schema file or dir to render'
+    required: true
+  outputs:
+    description: 'Path to output directory (if directory input) or file (if file input)'
+    required: true
+  output-format:
+    description: 'Format for rendered docs. html (default) or md'
+    required: false
+    default: html
+runs:
+  using: 'composite'
+  steps:
+    - uses: actions/checkout@v4
+
+    - name: Render Docs
+      uses: RMI-PACTA/actions/actions/json-schema/render-docs@json-schema
+      with:
+        input-files: ${{ inputs.input-files }}
+        outputs: ${{ inputs.outputs }}
+        output-format: $${{ inputs.output-format }}
+
+    - name: Check for changed files
+      shell: bash
+      env:
+        OUTPUTS: ${{ inputs.outputs }}
+      run: |
+        git add --all
+        changes=$(git diff-index HEAD --name-only -- $OUTPUTS)
+        if [ -n "$changes" ]; then
+          echo "Changes found after documenting."
+          git --no-pager diff
+          echo "$changes"
+          echo "Please update documentation."
+          exit 1
+        else
+          echo "No changes found after documenting."
+          exit 0
+        fi

actions/json-schema/render-docs/Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.12.5-alpine
+
+ENV PIP_ROOT_USER_ACTION=ignore
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir \
+      json-schema-for-humans==1.0.2
+
+COPY config.json /app/config.json
+COPY entrypoint.sh /app/entrypoint.sh
+
+CMD ["/app/entrypoint.sh"]

actions/json-schema/render-docs/README.md

@@ -0,0 +1,38 @@
+# Render JSON Schema documentation
+
+This action uses [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) to render documentation for JSON schemata.
+
+## Inputs
+
+## `input-files`
+
+**Required**
+Path to JSON schema file or directory of files to be processed.
+See [json-schema-for-humans documentation](https://github.com/coveooss/json-schema-for-humans?tab=readme-ov-file#usage) for more details.
+
+## `outputs`
+
+**Required**
+Path to directory (or filename if rendering single file) for rendered documentation to be written..
+See [json-schema-for-humans documentation](https://github.com/coveooss/json-schema-for-humans?tab=readme-ov-file#usage) for more details.
+
+## `output-format`
+
+Default: `html`.
+Should the rendered documentation be `html` or markdown (`md`)
+
+## Outputs
+
+None
+
+## Example usage
+
+```yaml
+      - id: render-json-schema
+        uses: RMI-PACTA/actions/actions/json-schema/render-docs@main
+        with:
+          input-files: 'inst/extdata/schema'
+          outputs: 'inst/extdata/schema'
+          output-format: html
+```
+

actions/json-schema/render-docs/action.yml

@@ -0,0 +1,21 @@
+# action.yml
+name: 'Render JSON Schema Documentation'
+description: 'Render JSON Schema docs usin json-schema-for-humans'
+inputs:
+  input-files:  # id of input
+    description: 'Schema file or dir to render'
+    required: true
+  outputs:
+    description: 'Path to output directory (if directory input) or file (if file input)'
+    required: true
+  output-format:
+    description: 'Format for rendered docs. html (default) or md'
+    required: false
+    default: html
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+  env:
+    INPUTS: ${{ inputs.input-files }}
+    OUTPUTS: ${{ inputs.outputs }}
+    INPUT_TEMPLATE_NAME: ${{ inputs.output-format }}

actions/json-schema/render-docs/config.json

@@ -0,0 +1,14 @@
+{
+  "expand_buttons": true,
+  "footer_show_time": false,
+  "minify": true,
+  "show_breadcrumbs": true,
+  "show_toc": true,
+  "template_name": "js_offline",
+  "with_footer": true,
+  "template_md_options": {
+    "badge_as_image": true,
+    "show_heading_numbers": true,
+    "show_array_restrictions": true
+  }
+}

actions/json-schema/render-docs/docker-compose.yml

@@ -0,0 +1,17 @@
+---
+services:
+  render-docs:
+    build: .
+    # stdin_open: true
+    # tty: true
+    # command: "sh"
+    environment:
+      GITHUB_OUTPUT: "/github/workspace/GITHUB_OUTPUT.txt"
+      INPUTS: "schema"
+      OUTPUTS: "schema-docs"
+      OUTPUT_FORMAT: "md"
+    volumes:
+      - type: bind
+        source: ${workspace:-./workspace}
+        target: /github/workspace
+        read_only: false

actions/json-schema/render-docs/entrypoint.sh

@@ -0,0 +1,44 @@
+#!/bin/sh
+
+# Check arguments
+if [ -z "$INPUTS" ]; then
+  echo "Input path is required"
+  exit 1
+fi
+
+if [ -z "$OUTPUTS" ]; then
+  echo "Output path is required"
+  exit 1
+fi
+
+TEMPLATE_NAME=$(
+  case "$INPUT_TEMPLATE_NAME" in
+    (md) echo "md";;
+    (html|js) echo "js_offline";;
+    (*) echo "";;
+  esac
+)
+
+if [ -n "$TEMPLATE_NAME" ]; then
+  CONFIG_OPTIONS="--config template_name=$TEMPLATE_NAME"
+fi
+
+# Use INPUT_<INPUT_NAME> to get the value of an input
+INPUT_PATH="/github/workspace/$INPUTS"
+OUTPUT_PATH="/github/workspace/$OUTPUTS"
+
+# Create directory if needed
+if [ ! -d "$OUTPUT_PATH" ]; then
+  echo "Creating directory $OUTPUT_PATH"
+  mkdir -p "$OUTPUT_PATH"
+fi
+
+# Write outputs to the $GITHUB_OUTPUT file
+generate-schema-doc \
+  $CONFIG_OPTIONS\
+  --config-file\
+  "/app/config.json"\
+  "$INPUT_PATH"\
+  "$OUTPUT_PATH"
+
+ls -l "$OUTPUT_PATH"