Add GitHub action to validate, lint and generate documentation (#274)

.github/scripts/validate-and-lint.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Validate the XML file structure and lint XSD and XML files, e.g. indentation
+#
+# You need the binary `xmllint`
+# apt-get install libxml2-utils
+
+# The -e flag causes the script to exit as soon as one command returns a non-zero exit code
+set -e
+
+echo "Validating XML file structure and linting XSD and XML files ..."
+
+PARSING_ERROR=0
+# Iterate all XML and XSD files
+while IFS= read -r -d $'\0' filename; do
+  # Prettify the file using xmllint and save the result to ${filename}.pretty
+  if XMLLINT_INDENT=$'\t' xmllint --encode UTF-8 --pretty 1 "${filename}" >"${filename}.pretty"; then
+    # Remove lines containing the term "xmlspy" to get rid of advertising this and save the result as ${filename}
+    grep -i -v "xmlspy" "${filename}.pretty" >"${filename}"
+  else
+    PARSING_ERROR=$?
+    echo -e "\033[0;Validating XML structure of file '${filename}' failed\033[0m"
+  fi
+  # Remove temp file
+  rm "${filename}.pretty"
+done < <(/usr/bin/find . -type f \( -name "*.xsd" -or -name "*.xml" \) -print0)
+
+if [ ${PARSING_ERROR} -ne 0 ]; then
+  exit ${PARSING_ERROR}
+fi
+echo -e '\033[0;32mFinished validating XML file structure and linting XSD and XML files\033[0m'

.github/scripts/validate-examples.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Validate all OJP XML examples from the examples/ directory against the OJP XSD schema
+#
+# You need the binary `xmllint`
+# apt-get install libxml2-utils
+
+# The -e flag causes the script to exit as soon as one command returns a non-zero exit code
+set -e
+
+echo "Validating OJP XML examples ..."
+
+if xmllint --noout --schema OJP.xsd examples/*/*.xml; then
+  echo -e '\033[0;32mValidating OJP XML examples succeeded\033[0m'
+else
+  echo -e '\033[0;31mValidating OJP XML examples failed\033[0m'
+  exit 1
+fi

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  # Triggers the workflow on push or pull request events but only for the "master" branch
+  push:
+    branches: [ "master", "main", "changes_for_v*" ]
+  pull_request:
+    branches: [ "master", "main", "changes_for_v*" ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+
+    steps:
+      - run: echo "Job was automatically triggered by a ${{ github.event_name }} event for branch ${{ github.ref }}"
+
+      - name: Check out repository code
+        uses: actions/checkout@v3
+        with:
+          # https://github.com/marketplace/actions/add-commit#working-with-prs
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.ref }}
+
+      - name: Install xmllint and xsltproc
+        run: |
+          sudo apt-get update
+          sudo apt-get install libxml2-utils xsltproc
+
+      - name: Validate structure and lint XSD and XML files
+        run: ./.github/scripts/validate-and-lint.sh
+
+      - name: Validate OJP XML examples
+        run: ./.github/scripts/validate-examples.sh
+
+      - name: Check schema structure for generation for documentation tables
+        run: ./docs/validate-schema-conventions.sh
+
+      - name: Generate documentation tables
+        run: ./docs/generate-tables.sh
+
+      - name: Commit changes
+        uses: EndBug/add-and-commit@v9 # https://github.com/marketplace/actions/add-commit
+        with:
+          default_author: github_actions
+          message: 'Lint and update documentation tables'

docs/generate-tables.sh

@@ -1,16 +1,15 @@
 #!/bin/bash
-# Script to generate the documentation tables as .html from the .xsd schema files
+# Generate the documentation tables as docs/generated/OJP.html from the .xsd schema files
 #
-# You need the binary `xsltproc` to generate html documentation from XML Schemas.
+# You need the binary `xsltproc`
 # apt-get install xsltproc
 
 # The -e flag causes the script to exit as soon as one command returns a non-zero exit code
 set -e
 
-echo "Generating documentation tables"
+echo "Generating documentation tables ..."
 
 base_dir="$(dirname "${0}")/.."
-xsd_dir=$base_dir
 xsl_dir=$base_dir/docs
 generated_dir="${base_dir}/docs/generated"
 
@@ -29,4 +28,4 @@ xsltproc --xinclude "${xsl_dir}"/ojp-prep-to-html-with-toc.xsl \
  "${generated_dir}"/OJP-prep.xml \
  >> "${generated_dir}"/OJP.html
 
-# end of file
+echo -e '\033[0;32mFinished generating documentation tables\033[0m'

docs/check-ojp-schemas.sh → docs/validate-schema-conventions.sh

@@ -1,29 +1,25 @@
 #!/bin/bash
-# Script to check the OJP XML Schemas on adherence to design and documentation conventions
+# Validate the OJP Schema on adherence to design and documentation conventions
 #
-# You need the binary `xsltproc` to runs the checks
+# You need the binary `xsltproc`
 # apt-get install xsltproc
 
 # The -e flag causes the script to exit as soon as one command returns a non-zero exit code
 set -e
 
-echo "Checking OJP XML Schemas..."
+echo "Validating OJP Schema conventions ..."
 
 base_dir="$(dirname "${0}")/.."
 xsl_dir=$base_dir/docs
 
 # Run the checks in the checker stylesheet
 saved_output=$(xsltproc --xinclude "${xsl_dir}"/check-ojp-schemas.xsl "${xsl_dir}"/schema-collection.xml 2>&1)
-EXITCODE=$?
-# echo $EXITCODE
 echo -e "$saved_output"
 errors=$(echo "$saved_output" | awk '/ERROR/')
 if [ -n "$errors" ]
 then
-  echo -e '\033[1;31mXML schema conventions: FAILED\033[0m'
+  echo -e '\033[1;31mValidating OJP Schema conventions failed\033[0m'
   exit 1
 else
-  echo -e '\033[0;32mXML schema conventions: PASSED\033[0m'
+  echo -e '\033[0;32mValidating OJP Schema conventions succeeded\033[0m'
 fi
-
-# end of file