Add scripts to generate documentation tables HTML from XSD (#131)

This change adds the scripts to generate documentation tables HTML from XSD and makes Travis render them during build. Like xmllint this may lead to an "Travis CI" commit on a feature branch to update the documentation tables if not run locally before committing. Those commits should be squash-and-merged like done for issues found with xmllint too. The documentation rendering still contains serveral issues in the state which have to be addressed as followups with Github issues each. This pull request contains the following changes: * First attempt to generate tables from XSD * Improved scripts * convert asciidoc to html using asciidoctor * rebased and adapted for current changes_for_v1.1 branch * changed directory for generated files * delete former asciidoc files on re-run * improved shell syntax * added comments * added .gitignore for generated files * consistent formatting and LF at line endings for theme.yml and ixsi-to-adoc-table.xsl * Changed sorting form alphabetical to order of appearance (addresses "12. The sorting of the chapters was done in alphabetical order? I would prefer the sorting from the XSD file.") * Generate a single adoc and html file for OJP from all Schema files * Rename xsl transformation file * Use XSD annotation>documentation as section title * Bugfix for broken formatting of top level element which happened due to the missing type definition (__ instead of _type_) * Bugfix for broken formatting of complex type element (which happened due to a missing line break) * Changes "type" to "complex type". * Added main schema annotation for each OJP xsd file and aligned "sections" * Added automatic generation of documentation tables using Travis * Render element ref if name is not set * In element only render | for last table column if it is not empty * Render cardinality of elements and groups as separate column (Fixes "2. The cardinality of elements (0..1, 1..unbounded, etc.) should get a separate column or be part of the type column.") Co-authored-by: Stefan de Konink <[email protected]>
VDVde · Dec 7, 2020 · 7097c72 · 7097c72
1 parent c18a4ea
commit 7097c72
Show file tree

Hide file tree

Showing 23 changed files with 11,608 additions and 87 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -1,10 +1,10 @@
 language: minimal
 
 before_script:
-  - sudo apt-get install -qq libxml2-utils
+  - sudo apt-get install -qq libxml2-utils xsltproc asciidoctor
 
 script:
-  - bash .travis/xmllint-check.sh
+  - bash .travis/xmllint-check.sh && bash docs/generate-tables.sh
 
 after_script:
   - bash .travis/travis-ci_git-commit.sh
diff --git a/OJP.xsd b/OJP.xsd
@@ -1,10 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns="http://www.siri.org.uk/siri" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.siri.org.uk/siri" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.0" id="OJP_siri">
+	<xs:annotation>
+		<xs:documentation>OJP.xsd - OJP messages as extension of SIRI</xs:documentation>
+	</xs:annotation>
 	<xs:import namespace="http://www.vdv.de/ojp" schemaLocation="./OJP/OJP_All.xsd"/>
 	<!-- ifopt must be imported before siri, otherwise xmllint fails -->
 	<xs:import namespace="http://www.ifopt.org.uk/ifopt" schemaLocation="./siri/ifopt/ifopt_allStopPlace-v0.3.xsd"/>
 	<xs:include schemaLocation="./siri/siri_model/siri_all-v2.0.xsd"/>
-	<!--== SIRI Request include OJP Requests ===================================================================== -->
 	<xs:element name="OJP">
 		<xs:annotation>
 			<xs:documentation>Root element for OJP messages based on SIRI message exchange protocol.</xs:documentation>
@@ -20,7 +22,6 @@
 			<xs:attribute name="version" type="xs:NMTOKEN" use="required" fixed="1.1-dev"/>
 		</xs:complexType>
 	</xs:element>
-	<!-- ======================================================================= -->
 	<xs:element name="OJPRequest" type="OJPRequestStructure">
 		<xs:annotation>
 			<xs:documentation>OJP Request - Groups individual functional requests.</xs:documentation>
@@ -34,7 +35,6 @@
 			<xs:group ref="RequestGroup"/>
 		</xs:sequence>
 	</xs:complexType>
-	<!-- ======================================================================= -->
 	<xs:element name="OJPResponse" type="OJPResponseStructure">
 		<xs:annotation>
 			<xs:documentation>OJP Request - Groups individual functional responses.</xs:documentation>

diff --git a/OJP/OJP_All.xsd b/OJP/OJP_All.xsd
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns="http://www.vdv.de/ojp" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.vdv.de/ojp" elementFormDefault="qualified" attributeFormDefault="unqualified">
+	<xs:annotation>
+		<xs:documentation>OJP/OJP_All.xsd - Includes for all OJP schema files</xs:documentation>
+	</xs:annotation>
 	<xs:include schemaLocation="OJP_Common.xsd"/>
 	<xs:include schemaLocation="OJP_FacilitySupport.xsd"/>
 	<xs:include schemaLocation="OJP_Fare.xsd"/>

diff --git a/OJP/OJP_Common.xsd b/OJP/OJP_Common.xsd
@@ -1,9 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns="http://www.vdv.de/ojp" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:siri="http://www.siri.org.uk/siri" targetNamespace="http://www.vdv.de/ojp" elementFormDefault="qualified" attributeFormDefault="unqualified">
+	<xs:annotation>
+		<xs:documentation>OJP/OJP_Common.xsd - Supporting definitions of common structures</xs:documentation>
+	</xs:annotation>
 	<xs:import namespace="http://www.siri.org.uk/siri" schemaLocation="../siri/siri_model/siri_all-v2.0.xsd"/>
 	<xs:include schemaLocation="OJP_All.xsd"/>
 	<xs:annotation>
-		<xs:documentation>========================================= General ================================================</xs:documentation>
+		<xs:documentation>========================================== General ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:complexType name="ErrorMessageStructure">
 		<xs:annotation>
@@ -40,15 +43,15 @@
 		</xs:sequence>
 	</xs:complexType>
 	<xs:annotation>
-		<xs:documentation>========================================= Participants =============================================</xs:documentation>
+		<xs:documentation>========================================== Participants ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:element name="ParticipantRef" type="siri:ParticipantRefStructure">
 		<xs:annotation>
 			<xs:documentation>Reference to a Participant ([equivalent of PARTICIPANT in SIRI] IT system that is participating in a communication with other participant(s))</xs:documentation>
 		</xs:annotation>
 	</xs:element>
 	<xs:annotation>
-		<xs:documentation>========================================= Operators =============================================</xs:documentation>
+		<xs:documentation>========================================== Operators ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:element name="OperatorRef" type="siri:OperatorRefStructure">
 		<xs:annotation>
@@ -73,7 +76,7 @@
 		</xs:sequence>
 	</xs:complexType>
 	<xs:annotation>
-		<xs:documentation>========================================= ProductCategories =============================================</xs:documentation>
+		<xs:documentation>========================================== ProductCategories ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:complexType name="ProductCategoryRefStructure">
 		<xs:annotation>
@@ -114,7 +117,9 @@
 			</xs:element>
 		</xs:sequence>
 	</xs:complexType>
-	<!-- ========================================= Journeys ============================== -->
+	<xs:annotation>
+		<xs:documentation>========================================== Journeys ==========================================</xs:documentation>
+	</xs:annotation>
 	<xs:simpleType name="JourneyCodeType">
 		<xs:annotation>
 			<xs:documentation>Identifier of a Journey</xs:documentation>
@@ -143,7 +148,9 @@
 			<xs:element ref="OperatingDayRef"/>
 		</xs:sequence>
 	</xs:group>
-	<!-- ========================================== Vehicles ============================= -->
+	<xs:annotation>
+		<xs:documentation>========================================== Vehicles ==========================================</xs:documentation>
+	</xs:annotation>
 	<xs:group name="TimedVehicleRefGroup">
 		<xs:annotation>
 			<xs:documentation>Reference to a vehicle for a specific point in time.</xs:documentation>
@@ -157,7 +164,9 @@
 			</xs:element>
 		</xs:sequence>
 	</xs:group>
-	<!-- ========================================== Sharing Services ========================== -->
+	<xs:annotation>
+		<xs:documentation>========================================== Sharing Services ==========================================</xs:documentation>
+	</xs:annotation>
 	<xs:simpleType name="SharingModelEnumeration">
 		<xs:annotation>
 			<xs:documentation>Sharing service loan and return scheme.</xs:documentation>
@@ -213,7 +222,9 @@
 			</xs:element>
 		</xs:sequence>
 	</xs:complexType>
-	<!-- ========================================== Owners ============================= -->
+	<xs:annotation>
+		<xs:documentation>========================================== Owners ==========================================</xs:documentation>
+	</xs:annotation>
 	<xs:simpleType name="OwnerCodeType">
 		<xs:annotation>
 			<xs:documentation>identifier of ORGANISATION with ownership as the RESPONSIBILITY ROLE</xs:documentation>
@@ -233,7 +244,9 @@
 			<xs:documentation>Reference to an  ORGANISATION with ownership as the RESPONSIBILITY ROLE</xs:documentation>
 		</xs:annotation>
 	</xs:element>
-	<!-- ========================================= Operating Days ============================== -->
+	<xs:annotation>
+		<xs:documentation>========================================== Operating Days ==========================================</xs:documentation>
+	</xs:annotation>
 	<xs:simpleType name="OperatingDayCodeType">
 		<xs:annotation>
 			<xs:documentation>Identifier of an Operating Day</xs:documentation>
@@ -330,7 +343,7 @@
 		</xs:restriction>
 	</xs:simpleType>
 	<xs:annotation>
-		<xs:documentation>==================================== General Attributes =============================================</xs:documentation>
+		<xs:documentation>========================================== General Attributes ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:complexType name="GeneralAttributeStructure">
 		<xs:annotation>

diff --git a/OJP/OJP_FacilitySupport.xsd b/OJP/OJP_FacilitySupport.xsd
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns="http://www.vdv.de/ojp" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:siri="http://www.siri.org.uk/siri" targetNamespace="http://www.vdv.de/ojp" elementFormDefault="qualified" attributeFormDefault="unqualified">
-	<xs:import namespace="http://www.siri.org.uk/siri" schemaLocation="../siri/siri_model/siri_all-v2.0.xsd"/>
-	<xs:include schemaLocation="OJP_All.xsd"/>
 	<xs:annotation>
-		<xs:documentation>==================================== Facilities from SIRI =============================================</xs:documentation>
+		<xs:documentation>OJP/OJP_FacilitySupport.xsd - Supporting definitions for facilities containing wrappers for SIRI</xs:documentation>
 	</xs:annotation>
+	<xs:import namespace="http://www.siri.org.uk/siri" schemaLocation="../siri/siri_model/siri_all-v2.0.xsd"/>
+	<xs:include schemaLocation="OJP_All.xsd"/>
 	<xs:group name="AllFacilitiesGroup">
 		<xs:annotation>
 			<xs:documentation>Wrapper for SIRI facilities.</xs:documentation>

diff --git a/OJP/OJP_Fare.xsd b/OJP/OJP_Fare.xsd
@@ -1,9 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns="http://www.vdv.de/ojp" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:siri="http://www.siri.org.uk/siri" targetNamespace="http://www.vdv.de/ojp" elementFormDefault="qualified" attributeFormDefault="unqualified">
+	<xs:annotation>
+		<xs:documentation>OJP/OJP_Fare.xsd - Request and response definitions for general, stop-specific and trip-specific fare information</xs:documentation>
+	</xs:annotation>
 	<xs:import namespace="http://www.siri.org.uk/siri" schemaLocation="../siri/siri_model/siri_all-v2.0.xsd"/>
 	<xs:include schemaLocation="OJP_All.xsd"/>
 	<xs:annotation>
-		<xs:documentation>====================================================Request definitions====================================================</xs:documentation>
+		<xs:documentation>========================================== Request definitions ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:group name="FareRequestGroup">
 		<xs:annotation>
@@ -90,7 +93,7 @@
 		</xs:sequence>
 	</xs:complexType>
 	<xs:annotation>
-		<xs:documentation>====================================================Response definitions====================================================</xs:documentation>
+		<xs:documentation>========================================== Response definitions ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:group name="FareResponseGroup">
 		<xs:sequence>

diff --git a/OJP/OJP_FareSupport.xsd b/OJP/OJP_FareSupport.xsd
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns="http://www.vdv.de/ojp" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.vdv.de/ojp" elementFormDefault="qualified" attributeFormDefault="unqualified">
+	<xs:annotation>
+		<xs:documentation>OJP/OJP_FareSupport.xsd - Supporting definitions for fare information on passenger trips</xs:documentation>
+	</xs:annotation>
 	<xs:include schemaLocation="OJP_All.xsd"/>
 	<xs:simpleType name="TypeOfFareClassEnumeration">
 		<xs:annotation>
@@ -26,7 +29,9 @@
 			<xs:enumeration value="unknown"/>
 		</xs:restriction>
 	</xs:simpleType>
-	<!-- ========================================== Fare Authority  ============================= -->
+	<xs:annotation>
+		<xs:documentation>========================================== Fare Authority ==========================================</xs:documentation>
+	</xs:annotation>
 	<xs:simpleType name="FareAuthorityCodeType">
 		<xs:annotation>
 			<xs:documentation>Identifier of a Fare Authority.</xs:documentation>
@@ -60,7 +65,7 @@
 		</xs:sequence>
 	</xs:group>
 	<xs:annotation>
-		<xs:documentation>========================================= Zones ================================================</xs:documentation>
+		<xs:documentation>========================================== Zones ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:simpleType name="TariffZoneCodeType">
 		<xs:annotation>
@@ -117,7 +122,7 @@
 		</xs:sequence>
 	</xs:complexType>
 	<xs:annotation>
-		<xs:documentation>========================================= Passengers ==============================================</xs:documentation>
+		<xs:documentation>========================================== Passengers ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:simpleType name="PassengerCategoryEnumeration">
 		<xs:annotation>
@@ -132,7 +137,7 @@
 		</xs:restriction>
 	</xs:simpleType>
 	<xs:annotation>
-		<xs:documentation>========================================= Booking  ==============================================</xs:documentation>
+		<xs:documentation>========================================== Booking ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:complexType name="BookingArrangementStructure">
 		<xs:annotation>
@@ -181,7 +186,7 @@
 		</xs:sequence>
 	</xs:complexType>
 	<xs:annotation>
-		<xs:documentation>========================================= Tickets ==============================================</xs:documentation>
+		<xs:documentation>========================================== Tickets ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:simpleType name="FareProductCodeType">
 		<xs:annotation>
@@ -336,7 +341,7 @@
 		</xs:sequence>
 	</xs:group>
 	<xs:annotation>
-		<xs:documentation>========================================= Trip Fare ==============================================</xs:documentation>
+		<xs:documentation>========================================== Trip Fare ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:group name="TripLegRangeGroup">
 		<xs:annotation>
@@ -384,7 +389,7 @@
 		</xs:sequence>
 	</xs:complexType>
 	<xs:annotation>
-		<xs:documentation>========================================= Fare request parameter ==============================================</xs:documentation>
+		<xs:documentation>========================================== Fare request parameter ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:complexType name="FarePassengerStructure">
 		<xs:annotation>

diff --git a/OJP/OJP_JourneySupport.xsd b/OJP/OJP_JourneySupport.xsd
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns="http://www.vdv.de/ojp" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:siri="http://www.siri.org.uk/siri" targetNamespace="http://www.vdv.de/ojp" elementFormDefault="qualified" attributeFormDefault="unqualified">
+	<xs:annotation>
+		<xs:documentation>OJP/OJP_JourneySupport.xsd - Supporting definitions for journeys on public transport vehicles</xs:documentation>
+	</xs:annotation>
 	<xs:import namespace="http://www.siri.org.uk/siri" schemaLocation="../siri/siri_model/siri_all-v2.0.xsd"/>
 	<xs:include schemaLocation="OJP_All.xsd"/>
 	<xs:complexType name="ServiceViaPointStructure">
@@ -210,7 +213,7 @@
 		</xs:sequence>
 	</xs:complexType>
 	<xs:annotation>
-		<xs:documentation>========================================= Times, Calls, Time context =================================================</xs:documentation>
+		<xs:documentation>========================================== Times, Calls, Time context ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:group name="TimeWindowGroup">
 		<xs:annotation>
@@ -470,7 +473,7 @@
 		</xs:sequence>
 	</xs:complexType>
 	<xs:annotation>
-		<xs:documentation>=========================================== Filter Groups ===========================================================</xs:documentation>
+		<xs:documentation>========================================== Filter Groups ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:group name="NumberOfResultsGroup">
 		<xs:annotation>
@@ -589,7 +592,7 @@
 		</xs:sequence>
 	</xs:group>
 	<xs:annotation>
-		<xs:documentation>=========================================== Leg Attributes =============================================</xs:documentation>
+		<xs:documentation>========================================== Leg Attributes ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:complexType name="LegAttributeStructure">
 		<xs:annotation>
@@ -613,7 +616,7 @@
 		</xs:complexContent>
 	</xs:complexType>
 	<xs:annotation>
-		<xs:documentation>=========================================== Leg Projection =============================================</xs:documentation>
+		<xs:documentation>========================================== Leg Projection ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:complexType name="LegTrackStructure">
 		<xs:annotation>

diff --git a/OJP/OJP_ModesSupport.xsd b/OJP/OJP_ModesSupport.xsd
@@ -1,9 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns="http://www.vdv.de/ojp" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:siri="http://www.siri.org.uk/siri" targetNamespace="http://www.vdv.de/ojp" elementFormDefault="qualified" attributeFormDefault="unqualified">
+	<xs:annotation>
+		<xs:documentation>OJP/OJP_ModesSupport.xsd - Supporting definitions for the classification of modes of transport</xs:documentation>
+	</xs:annotation>
 	<xs:import namespace="http://www.siri.org.uk/siri" schemaLocation="../siri/siri_model/siri_all-v2.0.xsd"/>
 	<xs:include schemaLocation="OJP_All.xsd"/>
 	<xs:annotation>
-		<xs:documentation>========================================= Individual Modes ============================</xs:documentation>
+		<xs:documentation>========================================== Individual Modes ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:simpleType name="IndividualModesEnumeration">
 		<xs:annotation>
@@ -85,7 +88,7 @@
 		</xs:restriction>
 	</xs:simpleType>
 	<xs:annotation>
-		<xs:documentation>========================================= Interchange Modes ============================</xs:documentation>
+		<xs:documentation>========================================== Interchange Modes ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:simpleType name="TransferModesEnumeration">
 		<xs:annotation>
@@ -106,7 +109,7 @@
 		</xs:restriction>
 	</xs:simpleType>
 	<xs:annotation>
-		<xs:documentation>========================================= Public Transport Modes ============================</xs:documentation>
+		<xs:documentation>========================================== Public Transport Modes ==========================================</xs:documentation>
 	</xs:annotation>
 	<xs:complexType name="ModeStructure">
 		<xs:annotation>
@@ -144,7 +147,9 @@
 			<xs:group ref="siri:PtModeChoiceGroup" minOccurs="0"/>
 		</xs:sequence>
 	</xs:group>
-	<!-- ================ Filters ======================================================= -->
+	<xs:annotation>
+		<xs:documentation>========================================== Filters ==========================================</xs:documentation>
+	</xs:annotation>
 	<xs:complexType name="PtModeFilterStructure">
 		<xs:annotation>
 			<xs:documentation>List of public transport modes ([from SIRI] mode of public transport service, corresponds to VEHICLE MODE) to include or exclude.</xs:documentation>