Switch to documentation tables based on xcore

VDVde · Mar 16, 2024 · 6b91031 · 6b91031
1 parent 049bf85
commit 6b91031
Show file tree

Hide file tree

Showing 44 changed files with 7,243 additions and 2,465 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -39,20 +39,17 @@ jobs:
           repository: ${{ github.event.pull_request.head.repo.full_name }}
           ref: ${{ github.event.pull_request.head.ref }}
 
-      - name: Install xmllint and xsltproc
+      - name: Install java, xmllint and xsltproc
         run: |
           sudo apt-get update
-          sudo apt-get install libxml2-utils xsltproc
+          sudo apt-get install default-jre 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
 
@@ -75,7 +72,7 @@ jobs:
           target-folder: "${{steps.get-branch-name.outputs.BRANCH_NAME}}"
 
       - name: Remove generated documentation tables
-        run: rm -rf ./docs/generated/index.html
+        run: rm -rf ./docs/generated/documentation-tables
 
       - name: Commit changes
         uses: EndBug/add-and-commit@v9 # https://github.com/marketplace/actions/add-commit

diff --git a/docs/asciidoc.css b/docs/asciidoc.css
diff --git a/docs/check-ojp-schemas.xsl b/docs/check-ojp-schemas.xsl
diff --git a/docs/generate-tables.sh b/docs/generate-tables.sh
@@ -1,34 +1,42 @@
 #!/bin/bash
-# Generate the documentation tables as docs/generated/OJP.html from the .xsd schema files
+# Generate the documentation tables in docs/generated/ from the .xsd schema files
 #
-# You need the binary `xsltproc`
-# apt-get install xsltproc
+# You need the binary `java`
+# apt-get install default-jre
 
 # The -e flag causes the script to exit as soon as one command returns a non-zero exit code
 set -e
 
+BASE_DIRECTORY=$(readlink -f "$(dirname "${0}")/..")
+XSL_DIRECTORY="${BASE_DIRECTORY}/docs/generate_tables"
+GENERATED_DIRECTORY="${BASE_DIRECTORY}/docs/generated"
+BASEX_JAR="/tmp/basex.jar"
+
+if [ ! -e ${BASEX_JAR} ]; then
+	echo "Downloading BaseX ..."
+	wget --output-document=${BASEX_JAR} https://files.basex.org/releases/10.6/BaseX106.jar
+fi
+
 echo "Generating documentation tables ..."
 
-base_dir="$(dirname "${0}")/.."
-xsl_dir=$base_dir/docs
-generated_dir="${base_dir}/docs/generated"
+# prepare GENERATED_DIRECTORY
+mkdir -p "${GENERATED_DIRECTORY}"
+rm -f "${GENERATED_DIRECTORY}"/*.html
 
-# prepare generated_dir
-mkdir -p "${generated_dir}"
-rm -f "${generated_dir}"/OJP-prep.xml "${generated_dir}"/*.adoc "${generated_dir}"/*.html
-cp "${xsl_dir}"/asciidoc.css "${generated_dir}"/
+cd "${XSL_DIRECTORY}"
 
-# create intermediate XML file for documentation
-xsltproc --xinclude "${xsl_dir}"/ojp-to-prepdoc.xsl \
- "${xsl_dir}"/schema-collection.xml \
- >> "${generated_dir}"/OJP-prep.xml
+java -cp ${BASEX_JAR} org.basex.BaseX \
+ -b report=contab \
+ -b dir="${BASE_DIRECTORY}" \
+ -b odir="${GENERATED_DIRECTORY}" \
+ -b custom=custom-ojp.xml \
+ -b dnamesExcluded=".git .github" \
+ xcore.xq
 
-# generate stand-alone HTML file for documentation
-xsltproc --xinclude "${xsl_dir}"/ojp-prep-to-html-with-toc.xsl \
- "${generated_dir}"/OJP-prep.xml \
- >> "${generated_dir}"/index.html
+# Remove interim edesc files
+rm -rf "${GENERATED_DIRECTORY}"/edesc
 
-# remove intermediate XML file
-rm -f "${generated_dir}"/OJP-prep.xml
+# move to speaking name
+mv "${GENERATED_DIRECTORY}"/contab "${GENERATED_DIRECTORY}"/documentation-tables
 
 echo -e '\033[0;32mFinished generating documentation tables\033[0m'
diff --git a/docs/generate_tables/custom-netex-perxsd.xml b/docs/generate_tables/custom-netex-perxsd.xml
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<custom>
+	<!-- Title appearing on the entry page -->
+	<systemTitle><strong>Ne</strong>twork <strong>T</strong>imetable <strong>EX</strong>change</systemTitle>
+	<!-- Standardized namespace bindings -->
+	<namespaces>
+		<namespace prefix="orc" uri="http://datex2.eu/schema/2_0RC1/2_0"/>
+		<namespace prefix="wsdl" uri="http://wsdl.siri.org.uk"/>
+		<namespace prefix="acsb" uri="http://www.ifopt.org.uk/acsb"/>
+		<namespace prefix="ifopt" uri="http://www.ifopt.org.uk/ifopt"/>
+		<namespace prefix="netex" uri="http://www.netex.org.uk/netex"/>
+		<namespace prefix="gml" uri="http://www.opengis.net/gml/3.2"/>
+		<namespace prefix="siri" uri="http://www.siri.org.uk/siri"/>
+		<namespace prefix="ojp" uri="http://www.vdv.de/ojp"/>
+	</namespaces>
+	<!-- Report type specific rules -->
+	<reportTypes/>
+</custom>
diff --git a/docs/generate_tables/custom-ojp-perxsd.xml b/docs/generate_tables/custom-ojp-perxsd.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<custom>
+	<!-- Title appearing on the entry page -->
+	<systemTitle><strong>O</strong>pen API for distributed <strong>J</strong>ourney <strong>P</strong>lanning</systemTitle>
+	<!-- Standardized namespace bindings -->
+	<namespaces>
+		<namespace prefix="orc" uri="http://datex2.eu/schema/2_0RC1/2_0"/>
+		<namespace prefix="wsdl" uri="http://wsdl.siri.org.uk"/>
+		<namespace prefix="acsb" uri="http://www.ifopt.org.uk/acsb"/>
+		<namespace prefix="ifopt" uri="http://www.ifopt.org.uk/ifopt"/>
+		<namespace prefix="netex" uri="http://www.netex.org.uk/netex"/>
+		<namespace prefix="gml" uri="http://www.opengis.net/gml/3.2"/>
+		<namespace prefix="siri" uri="http://www.siri.org.uk/siri"/>
+		<namespace prefix="ojp" uri="http://www.vdv.de/ojp"/>
+	</namespaces>
+	<!-- Report type specific rules -->
+	<reportTypes/>
+	<!--
+    <domains>
+        <domain name="xsd">
+            <content>
+                <foreach>xsd</foreach>
+            </content>
+            <processing>
+                <outputPath>../output/ojp2</outputPath>
+                <title>#xsdname</title>
+            </processing>
+        </domain>
+    </domains>
+    -->
+</custom>
diff --git a/docs/generate_tables/custom-ojp.xml b/docs/generate_tables/custom-ojp.xml
@@ -0,0 +1,136 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<custom>
+	<!-- Title appearing on the entry page -->
+	<systemTitle><strong>O</strong>pen API for distributed <strong>J</strong>ourney 
+        <strong>P</strong>lanning</systemTitle>
+	<!-- Standardized namespace bindings -->
+	<namespaces>
+		<namespace prefix="orc" uri="http://datex2.eu/schema/2_0RC1/2_0"/>
+		<namespace prefix="wsdl" uri="http://wsdl.siri.org.uk"/>
+		<namespace prefix="acsb" uri="http://www.ifopt.org.uk/acsb"/>
+		<namespace prefix="ifopt" uri="http://www.ifopt.org.uk/ifopt"/>
+		<namespace prefix="netex" uri="http://www.netex.org.uk/netex"/>
+		<namespace prefix="gml" uri="http://www.opengis.net/gml/3.2"/>
+		<namespace prefix="siri" uri="http://www.siri.org.uk/siri"/>
+		<namespace prefix="ojp" uri="http://www.vdv.de/ojp"/>
+	</namespaces>
+	<!-- Report type specific rules -->
+	<reportTypes/>
+	<domains>
+		<domain name="datex2">
+			<content>
+				<targetNamespace>http://datex2.eu/schema/2_0RC1/2_0</targetNamespace>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed <strong>J</strong>ourney <strong>P</strong>lanning (datex2)</title>
+				<titleEnumDict>OJP Enumeration Dictionary - DATEX2</titleEnumDict>
+				<reportFileBaseName>datex2</reportFileBaseName>
+				<reportTypes/>
+			</processing>
+		</domain>
+		<domain name="siri-wsdl">
+			<content>
+				<targetNamespace>http://wsdl.siri.org.uk</targetNamespace>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed <strong>J</strong>ourney <strong>P</strong>lanning (wsdl)</title>
+				<titleEnumDict>OJP Enumeration Dictionary - WSDL</titleEnumDict>
+				<reportFileBaseName>siri-wsdl</reportFileBaseName>
+				<reportTypes/>
+			</processing>
+		</domain>
+		<domain name="acsb">
+			<content>
+				<targetNamespace>http://www.ifopt.org.uk/acsb</targetNamespace>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed <strong>J</strong>ourney <strong>P</strong>lanning (ACSB)</title>
+				<titleEnumDict>OJP Enumeration Dictionary - ACSB</titleEnumDict>
+				<reportFileBaseName>acsb</reportFileBaseName>
+				<reportTypes/>
+			</processing>
+		</domain>
+		<domain name="ifopt">
+			<content>
+				<targetNamespace>http://www.ifopt.org.uk/ifopt</targetNamespace>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed <strong>J</strong>ourney <strong>P</strong>lanning (IFOPT)</title>
+				<titleEnumDict>OJP Enumeration Dictionary - IFOPT</titleEnumDict>
+				<reportFileBaseName>ifopt</reportFileBaseName>
+				<reportTypes/>
+			</processing>
+		</domain>
+		<domain name="opengis">
+			<content>
+				<targetNamespace>http://www.opengis.net/gml/3.2</targetNamespace>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed <strong>J</strong>ourney <strong>P</strong>lanning (GML)</title>
+				<titleEnumDict>OJP Enumeration Dictionary - OJP</titleEnumDict>
+				<reportFileBaseName>gml</reportFileBaseName>
+				<reportTypes/>
+			</processing>
+		</domain>
+		<domain name="siri">
+			<content>
+				<targetNamespace>http://www.siri.org.uk/siri</targetNamespace>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed <strong>J</strong>ourney <strong>P</strong>lanning (SIRI)</title>
+				<reportFileBaseName>siri</reportFileBaseName>
+				<reportTypes/>
+			</processing>
+		</domain>
+		<domain name="ojp">
+			<content>
+				<targetNamespace>http://www.vdv.de/ojp</targetNamespace>
+				<files dir="ojp" name="ojp.xsd"/>
+			</content>
+			<processing>
+				<title>OJP - <strong>O</strong>pen API for distributed <strong>J</strong>ourney <strong>P</strong>lanning</title>
+				<reportFileBaseName>ojp</reportFileBaseName>
+				<order>
+					<first>
+						<xsd filePath="OJP.xsd"/>
+						<xsd filePath="ojp/OJP_Requests.xsd"/>
+						<xsd filePath="ojp/OJP_RequestSupport.xsd"/>
+						<xsd filePath="ojp/OJP_Fare.xsd"/>
+						<xsd filePath="ojp/OJP_FareSupport.xsd"/>
+						<xsd filePath="ojp/OJP_Lines.xsd"/>
+						<xsd filePath="ojp/OJP_Locations.xsd"/>
+						<xsd filePath="ojp/OJP_PlaceSupport.xsd"/>
+						<xsd filePath="ojp/OJP_StopEvents.xsd"/>
+						<xsd filePath="ojp/OJP_TripInfo.xsd"/>
+						<xsd filePath="ojp/OJP_Trips.xsd"/>
+						<xsd filePath="ojp/OJP_JourneySupport.xsd"/>
+						<xsd filePath="ojp/OJP_Availability.xsd"/>
+						<xsd filePath="ojp/OJP_Common.xsd"/>
+						<xsd filePath="ojp/OJP_FacilitySupport.xsd"/>
+						<xsd filePath="ojp/OJP_ModesSupport.xsd"/>
+						<xsd filePath="ojp/OJP_SituationSupport.xsd"/>
+						<xsd filePath="ojp/OJP_Utility.xsd"/>
+						<xsd filePath="ojp/OJP_Status.xsd"/>
+					</first>
+				</order>
+				<reportTypes>
+					<!-- Report "edisc-html" -->
+					<reportType name="contab">
+						<!-- XSD titles -->
+						<xsdTitle pref1="singleSentenceAnno" pref2="fileName"/>
+						<!-- Name edits - prefix removal and substring replacement -->
+						<nameEdit>
+							<comp removePrefix="ojp" use="main" kind="element"/>
+							<comp removePrefix="ojp" use="main" kind="complexType"/>
+							<comp removePrefix="ojp" use="main" kind="group"/>
+							<comp removePrefix="ojp" use="main" kind="simpleType"/>
+							<comp removePrefix="ojp" use="sub" kind="element"/>
+							<comp removePrefix="ojp" use="sub" kind="group" replace="Group$" with=""/>
+							<comp removePrefix="ojp" use="sub" kind="complexType" replace="Structure$" with=""/>
+						</nameEdit>
+					</reportType>
+				</reportTypes>
+			</processing>
+		</domain>
+	</domains>
+</custom>
diff --git a/docs/generate_tables/custom-siri-perxsd.xml b/docs/generate_tables/custom-siri-perxsd.xml
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<custom>
+	<!-- Title appearing on the entry page -->
+	<systemTitle><strong>S</strong>erver <strong>I</strong>nterface for 
+        <strong>R</strong>eal-time <strong>I</strong>nformation (SIRI)</systemTitle>
+	<!-- Standardized namespace bindings -->
+	<namespaces>
+		<namespace prefix="orc" uri="http://datex2.eu/schema/2_0RC1/2_0"/>
+		<namespace prefix="wsdl" uri="http://wsdl.siri.org.uk"/>
+		<namespace prefix="acsb" uri="http://www.ifopt.org.uk/acsb"/>
+		<namespace prefix="ifopt" uri="http://www.ifopt.org.uk/ifopt"/>
+		<namespace prefix="netex" uri="http://www.netex.org.uk/netex"/>
+		<namespace prefix="gml" uri="http://www.opengis.net/gml/3.2"/>
+		<namespace prefix="siri" uri="http://www.siri.org.uk/siri"/>
+		<namespace prefix="ojp" uri="http://www.vdv.de/ojp"/>
+	</namespaces>
+	<!-- Report type specific rules -->
+	<reportTypes/>
+</custom>