Generate documentation automatically

MobilityDB · Oct 4, 2023 · 6dbae0a · 6dbae0a
1 parent 2cf2113
commit 6dbae0a
Show file tree

Hide file tree

Showing 65 changed files with 123 additions and 6 deletions.
diff --git a/.github/workflows/generate_docs.yml b/.github/workflows/generate_docs.yml
@@ -0,0 +1,95 @@
+# Automatic generation of documentation will be copied and checked into the 
+# gh-pages branch.
+name: Documentation generation CI
+
+on:
+  push:
+    paths:
+      - '.github/workflows/generate_docs.yml'
+      - 'docs/**'
+    branches:
+      - master
+      - develop
+
+jobs:
+  build:
+    name: Generate documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      # checkout branch
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: docs
+
+      # Install dblatex
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y dblatex dbtoepub xsltproc
+
+      # generate the documentation files
+      - name: Generate documentation
+        run: |
+          cd docs
+          dblatex -s texstyle.sty mobilitydb-workshop.xml
+          dbtoepub -o mobilitydb-workshop.epub mobilitydb-workshop.xml
+          mkdir html
+          xsltproc --stringparam html.stylesheet "docbook.css" --stringparam chunker.output.encoding "UTF-8" --xinclude -o html/index.html /usr/share/xml/docbook/stylesheet/docbook-xsl/html/chunk.xsl mobilitydb-workshop.xml
+          cp -r images docbook.css html/
+          cp docbook.css html/
+
+      # store the documentation files
+      - name: Upload output directory
+        uses: actions/upload-artifact@v2
+        with:
+          name: doc-files
+          path: |
+            docs/index.md
+            docs/mobilitydb-workshop.pdf
+            docs/mobilitydb-workshop.epub
+            docs/html/docbook.css
+            docs/html/images/*
+            docs/html/*.html
+          retention-days: 1
+
+
+  copy:
+    name: Deploy documentation
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      # checkout the gh-pages branch
+      - uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+
+      # download the doc files, most of which are generated above
+      - name: Download output directory
+        uses: actions/download-artifact@v2
+        with:
+          name: doc-files
+          path: docs-temp
+
+      # Rename the directory to master
+      - name: Rename the directory to master
+        if: ${{ github.ref == 'refs/heads/master' }}
+        run: |
+          rm -rf master
+          mv docs-temp master
+
+      # Rename the directory to master
+      - name: Rename the directory to develop
+        if: ${{ github.ref == 'refs/heads/develop' }}
+        run: |
+          rm -rf develop
+          mv docs-temp develop
+
+      # add, commit and push to gh-pages
+      - name: Commit changes
+        uses: EndBug/add-and-commit@v9
+        with:
+          message: 'Update docs'
+          branch: gh-pages
diff --git a/README.md b/README.md
@@ -6,10 +6,10 @@ of the modules.
 
 ## Documentation
 
-You can generate the workshop documentation from the sources. Go to `/doc` directory and run: 
+You can generate the workshop documentation from the sources. Go to `/docs` directory and run: 
 *  In HTML format
     ```bash
-    xsltproc --stringparam html.stylesheet "docbook.css" --xinclude -o index.html /usr/share/xml/docbook/stylesheet/docbook-xsl/html/chunk.xsl mobilitydb-workshop.xml
+    xsltproc --stringparam html.stylesheet "docbook.css" --stringparam chunker.output.encoding "UTF-8"  --xinclude -o index.html /usr/share/xml/docbook/stylesheet/docbook-xsl/html/chunk.xsl mobilitydb-workshop.xml
     ```
 *  In PDF format
     ```bash
@@ -21,13 +21,21 @@ You can generate the workshop documentation from the sources. Go to `/doc` direc
     ```
 In addition, pre-generated versions of them are available.
 
-*  In HTML format: https://docs.mobilitydb.com/MobilityDB-workshop/master/
-*  In PDF format: https://docs.mobilitydb.com/MobilityDB-workshop/master/mobilitydb-workshop.pdf
-*  In EPUB format: https://docs.mobilitydb.com/MobilityDB-workshop/master/mobilitydb-workshop.epub
+Master branch:
+
+*  In HTML format: https://mobilitydb.github.io/MobilityDB-workshop/master/html/index.html
+*  In PDF format: https://mobilitydb.github.io/MobilityDB-workshop/master/mobilitydb-workshop.pdf
+*  In EPUB format: https://mobilitydb.github.io/MobilityDB-workshop/master/mobilitydb-workshop.epub
+
+Develop branch:
+
+*  In HTML format: https://mobilitydb.github.io/MobilityDB-workshop/develop/html/index.html
+*  In PDF format: https://mobilitydb.github.io/MobilityDB-workshop/develop/mobilitydb-workshop.pdf
+*  In EPUB format: https://mobilitydb.github.io/MobilityDB-workshop/develop/mobilitydb-workshop.epub
 
 ## How the Repo is Organized
 - `/data`: raw data files used for some workshops
-- `/doc`: files needed to generate the workshop documentation from sources
+- `/docs`: files needed to generate the workshop documentation from sources
 
 ## Docker container
 

diff --git a/doc/AIS.xml → docs/AIS.xml b/doc/AIS.xml → docs/AIS.xml
diff --git a/doc/AIS_Dashboard.xml → docs/AIS_Dashboard.xml b/doc/AIS_Dashboard.xml → docs/AIS_Dashboard.xml
diff --git a/doc/FlightDataDashboard.xml → docs/FlightDataDashboard.xml b/doc/FlightDataDashboard.xml → docs/FlightDataDashboard.xml
diff --git a/doc/GPX.xml → docs/GPX.xml b/doc/GPX.xml → docs/GPX.xml
diff --git a/doc/GTFS.xml → docs/GTFS.xml b/doc/GTFS.xml → docs/GTFS.xml
diff --git a/doc/docbook.css → docs/docbook.css b/doc/docbook.css → docs/docbook.css
diff --git a/...ssigningTimeRangeUsingGlobalVariables.png → ...ssigningTimeRangeUsingGlobalVariables.png b/...ssigningTimeRangeUsingGlobalVariables.png → ...ssigningTimeRangeUsingGlobalVariables.png
diff --git a/...mages/AverageFlightSpeedVisualization.png → ...mages/AverageFlightSpeedVisualization.png b/...mages/AverageFlightSpeedVisualization.png → ...mages/AverageFlightSpeedVisualization.png
diff --git a/...lorSchemeInStandardOptionsDialogueBox.png → ...lorSchemeInStandardOptionsDialogueBox.png b/...lorSchemeInStandardOptionsDialogueBox.png → ...lorSchemeInStandardOptionsDialogueBox.png
diff --git a/doc/images/ChoosingVisualizationType.png → docs/images/ChoosingVisualizationType.png b/doc/images/ChoosingVisualizationType.png → docs/images/ChoosingVisualizationType.png
diff --git a/...atingUserDefinedListOfCustomVariables.png → ...atingUserDefinedListOfCustomVariables.png b/...atingUserDefinedListOfCustomVariables.png → ...atingUserDefinedListOfCustomVariables.png
diff --git a/doc/images/DashboardSettingsGearBox.png → docs/images/DashboardSettingsGearBox.png b/doc/images/DashboardSettingsGearBox.png → docs/images/DashboardSettingsGearBox.png
diff --git a/doc/images/DataSourceSettings.png → docs/images/DataSourceSettings.png b/doc/images/DataSourceSettings.png → docs/images/DataSourceSettings.png
diff --git a/...ages/DatatypeTransformationsInGrafana.png → ...ages/DatatypeTransformationsInGrafana.png b/...ages/DatatypeTransformationsInGrafana.png → ...ages/DatatypeTransformationsInGrafana.png
diff --git a/...isualizationWithMultipleFlightAscents.png → ...isualizationWithMultipleFlightAscents.png b/...isualizationWithMultipleFlightAscents.png → ...isualizationWithMultipleFlightAscents.png
diff --git a/...s/FlightDashboard_final_visualization.png → ...s/FlightDashboard_final_visualization.png b/...s/FlightDashboard_final_visualization.png → ...s/FlightDashboard_final_visualization.png
diff --git a/doc/images/FlightTrajSampleTable.png → docs/images/FlightTrajSampleTable.png b/doc/images/FlightTrajSampleTable.png → docs/images/FlightTrajSampleTable.png
diff --git a/...tingWithGeometricEnvelopVisualization.png → ...tingWithGeometricEnvelopVisualization.png b/...tingWithGeometricEnvelopVisualization.png → ...tingWithGeometricEnvelopVisualization.png
diff --git a/doc/images/FullDashboard.png → docs/images/FullDashboard.png b/doc/images/FullDashboard.png → docs/images/FullDashboard.png
diff --git a/doc/images/GrafanaTimerangePanelOpen.png → docs/images/GrafanaTimerangePanelOpen.png b/doc/images/GrafanaTimerangePanelOpen.png → docs/images/GrafanaTimerangePanelOpen.png
diff --git a/...idualShipSpeedStatisticsVisualization.png → ...idualShipSpeedStatisticsVisualization.png b/...idualShipSpeedStatisticsVisualization.png → ...idualShipSpeedStatisticsVisualization.png
diff --git a/doc/images/LocationHistory.png → docs/images/LocationHistory.png b/doc/images/LocationHistory.png → docs/images/LocationHistory.png
diff --git a/...MultipleLayersInDataLayersDialogueBox.png → ...MultipleLayersInDataLayersDialogueBox.png b/...MultipleLayersInDataLayersDialogueBox.png → ...MultipleLayersInDataLayersDialogueBox.png
diff --git a/...es/MultipleQueriesSingleVisualization.png → ...es/MultipleQueriesSingleVisualization.png b/...es/MultipleQueriesSingleVisualization.png → ...es/MultipleQueriesSingleVisualization.png
diff --git a/...TheSameShipAtVariousTimesWhileInAPort.png → ...TheSameShipAtVariousTimesWhileInAPort.png b/...TheSameShipAtVariousTimesWhileInAPort.png → ...TheSameShipAtVariousTimesWhileInAPort.png
diff --git a/...images/OverrideOptionsMultipleQueries.png → ...images/OverrideOptionsMultipleQueries.png b/...images/OverrideOptionsMultipleQueries.png → ...images/OverrideOptionsMultipleQueries.png
diff --git a/...uteUsageFrequencyHeatMapVisualization.png → ...uteUsageFrequencyHeatMapVisualization.png b/...uteUsageFrequencyHeatMapVisualization.png → ...uteUsageFrequencyHeatMapVisualization.png
diff --git a/...SelectingVariablesInDashboardSettings.png → ...SelectingVariablesInDashboardSettings.png b/...SelectingVariablesInDashboardSettings.png → ...SelectingVariablesInDashboardSettings.png
diff --git a/...ettingInitialViewInMapViewDialogueBox.png → ...ettingInitialViewInMapViewDialogueBox.png b/...ettingInitialViewInMapViewDialogueBox.png → ...ettingInitialViewInMapViewDialogueBox.png
diff --git a/...ettingUpHeatMapInDataLayerDialogueBox.png → ...ettingUpHeatMapInDataLayerDialogueBox.png b/...ettingUpHeatMapInDataLayerDialogueBox.png → ...ettingUpHeatMapInDataLayerDialogueBox.png
diff --git a/doc/images/SingleAirframeAltitudeVsTime.png → docs/images/SingleAirframeAltitudeVsTime.png b/doc/images/SingleAirframeAltitudeVsTime.png → docs/images/SingleAirframeAltitudeVsTime.png
diff --git a/doc/images/SingleAirframeCallsignVsTime.png → docs/images/SingleAirframeCallsignVsTime.png b/doc/images/SingleAirframeCallsignVsTime.png → docs/images/SingleAirframeCallsignVsTime.png
diff --git a/doc/images/SingleAirframeGeopointsVsTime.png → .../images/SingleAirframeGeopointsVsTime.png b/doc/images/SingleAirframeGeopointsVsTime.png → .../images/SingleAirframeGeopointsVsTime.png
diff --git a/doc/images/SingleAirframeRow1.png → docs/images/SingleAirframeRow1.png b/doc/images/SingleAirframeRow1.png → docs/images/SingleAirframeRow1.png
diff --git a/doc/images/SingleAirframeTrajTable.png → docs/images/SingleAirframeTrajTable.png b/doc/images/SingleAirframeTrajTable.png → docs/images/SingleAirframeTrajTable.png
diff --git a/doc/images/SingleAirframeVelocityVsTime.png → docs/images/SingleAirframeVelocityVsTime.png b/doc/images/SingleAirframeVelocityVsTime.png → docs/images/SingleAirframeVelocityVsTime.png
diff --git a/doc/images/SingleAirframeVertrateVsTime.png → docs/images/SingleAirframeVertrateVsTime.png b/doc/images/SingleAirframeVertrateVsTime.png → docs/images/SingleAirframeVertrateVsTime.png
diff --git a/doc/images/StandardOptionsDialogueBox.png → docs/images/StandardOptionsDialogueBox.png b/doc/images/StandardOptionsDialogueBox.png → docs/images/StandardOptionsDialogueBox.png
diff --git a/doc/images/StatStylesDialogueBox.png → docs/images/StatStylesDialogueBox.png b/doc/images/StatStylesDialogueBox.png → docs/images/StatStylesDialogueBox.png
diff --git a/...es/StatisticVisualizationByFlightType.png → ...es/StatisticVisualizationByFlightType.png b/...es/StatisticVisualizationByFlightType.png → ...es/StatisticVisualizationByFlightType.png
diff --git a/doc/images/ThresholdsDialogueBox.png → docs/images/ThresholdsDialogueBox.png b/doc/images/ThresholdsDialogueBox.png → docs/images/ThresholdsDialogueBox.png
diff --git a/doc/images/ValueOptionsDialogueBox.png → docs/images/ValueOptionsDialogueBox.png b/doc/images/ValueOptionsDialogueBox.png → docs/images/ValueOptionsDialogueBox.png
diff --git a/...etryIntersectionUsingDynamicVariables.png → ...etryIntersectionUsingDynamicVariables.png b/...etryIntersectionUsingDynamicVariables.png → ...etryIntersectionUsingDynamicVariables.png
diff --git a/...lizationOfShipsWithin300mUsingHeatMap.png → ...lizationOfShipsWithin300mUsingHeatMap.png b/...lizationOfShipsWithin300mUsingHeatMap.png → ...lizationOfShipsWithin300mUsingHeatMap.png
diff --git a/doc/images/ZoomedInViewOfFlightAscent.png → docs/images/ZoomedInViewOfFlightAscent.png b/doc/images/ZoomedInViewOfFlightAscent.png → docs/images/ZoomedInViewOfFlightAscent.png
diff --git a/doc/images/approach1.png → docs/images/approach1.png b/doc/images/approach1.png → docs/images/approach1.png
diff --git a/doc/images/approach2.png → docs/images/approach2.png b/doc/images/approach2.png → docs/images/approach2.png
diff --git a/doc/images/mobilitydb-logo.png → docs/images/mobilitydb-logo.png b/doc/images/mobilitydb-logo.png → docs/images/mobilitydb-logo.png
diff --git a/doc/images/points.png → docs/images/points.png b/doc/images/points.png → docs/images/points.png
diff --git a/doc/images/stib.png → docs/images/stib.png b/doc/images/stib.png → docs/images/stib.png
diff --git a/doc/images/trajApproach.png → docs/images/trajApproach.png b/doc/images/trajApproach.png → docs/images/trajApproach.png
diff --git a/doc/images/trajFerries.png → docs/images/trajFerries.png b/doc/images/trajFerries.png → docs/images/trajFerries.png
diff --git a/doc/images/trajFerry.png → docs/images/trajFerry.png b/doc/images/trajFerry.png → docs/images/trajFerry.png
diff --git a/doc/images/trajs.png → docs/images/trajs.png b/doc/images/trajs.png → docs/images/trajs.png
diff --git a/doc/images/trajsFiltered.png → docs/images/trajsFiltered.png b/doc/images/trajsFiltered.png → docs/images/trajsFiltered.png
diff --git a/doc/images/trajsShort.png → docs/images/trajsShort.png b/doc/images/trajsShort.png → docs/images/trajsShort.png
diff --git a/doc/images/trajsWrongAzimuth.png → docs/images/trajsWrongAzimuth.png b/doc/images/trajsWrongAzimuth.png → docs/images/trajsWrongAzimuth.png
diff --git a/doc/images/trajsWrongSpeed.png → docs/images/trajsWrongSpeed.png b/doc/images/trajsWrongSpeed.png → docs/images/trajsWrongSpeed.png
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,14 @@
+<img src="https://MobilityDB.github.io/MobilityDB-workshop/images/mobilitydb-logo.png"
+     alt="MobilityDB icon"
+     style="float: center; margin-right: 10px;" />
+
+-----------------------------------------------
+# **Documentation of the MobilityDB Workshop**
+-----------------------------------------------
+
+
+The documentation is available in the following formats
+
+* [PDF](./mobilitydb-workshop.pdf)
+* [EPUB](./mobilitydb-workshop.epub)
+* [HTML](./html/index.html)
diff --git a/doc/install.sh → docs/install.sh b/doc/install.sh → docs/install.sh
diff --git a/doc/location_history.xml → docs/location_history.xml b/doc/location_history.xml → docs/location_history.xml
diff --git a/doc/mobilitydb-workshop.xml → docs/mobilitydb-workshop.xml b/doc/mobilitydb-workshop.xml → docs/mobilitydb-workshop.xml
diff --git a/doc/texstyle.sty → docs/texstyle.sty b/doc/texstyle.sty → docs/texstyle.sty