diff --git a/.github/workflows/generate_docs.yml b/.github/workflows/generate_docs.yml new file mode 100644 index 0000000..7dc5391 --- /dev/null +++ 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 index 18fe24b..297f206 100644 --- 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 b/docs/AIS.xml similarity index 100% rename from doc/AIS.xml rename to docs/AIS.xml diff --git a/doc/AIS_Dashboard.xml b/docs/AIS_Dashboard.xml similarity index 100% rename from doc/AIS_Dashboard.xml rename to docs/AIS_Dashboard.xml diff --git a/doc/FlightDataDashboard.xml b/docs/FlightDataDashboard.xml similarity index 100% rename from doc/FlightDataDashboard.xml rename to docs/FlightDataDashboard.xml diff --git a/doc/GPX.xml b/docs/GPX.xml similarity index 100% rename from doc/GPX.xml rename to docs/GPX.xml diff --git a/doc/GTFS.xml b/docs/GTFS.xml similarity index 100% rename from doc/GTFS.xml rename to docs/GTFS.xml diff --git a/doc/docbook.css b/docs/docbook.css similarity index 100% rename from doc/docbook.css rename to docs/docbook.css diff --git a/doc/images/AssigningTimeRangeUsingGlobalVariables.png b/docs/images/AssigningTimeRangeUsingGlobalVariables.png similarity index 100% rename from doc/images/AssigningTimeRangeUsingGlobalVariables.png rename to docs/images/AssigningTimeRangeUsingGlobalVariables.png diff --git a/doc/images/AverageFlightSpeedVisualization.png b/docs/images/AverageFlightSpeedVisualization.png similarity index 100% rename from doc/images/AverageFlightSpeedVisualization.png rename to docs/images/AverageFlightSpeedVisualization.png diff --git a/doc/images/ChoosingColorSchemeInStandardOptionsDialogueBox.png b/docs/images/ChoosingColorSchemeInStandardOptionsDialogueBox.png similarity index 100% rename from doc/images/ChoosingColorSchemeInStandardOptionsDialogueBox.png rename to docs/images/ChoosingColorSchemeInStandardOptionsDialogueBox.png diff --git a/doc/images/ChoosingVisualizationType.png b/docs/images/ChoosingVisualizationType.png similarity index 100% rename from doc/images/ChoosingVisualizationType.png rename to docs/images/ChoosingVisualizationType.png diff --git a/doc/images/CreatingUserDefinedListOfCustomVariables.png b/docs/images/CreatingUserDefinedListOfCustomVariables.png similarity index 100% rename from doc/images/CreatingUserDefinedListOfCustomVariables.png rename to docs/images/CreatingUserDefinedListOfCustomVariables.png diff --git a/doc/images/DashboardSettingsGearBox.png b/docs/images/DashboardSettingsGearBox.png similarity index 100% rename from doc/images/DashboardSettingsGearBox.png rename to docs/images/DashboardSettingsGearBox.png diff --git a/doc/images/DataSourceSettings.png b/docs/images/DataSourceSettings.png similarity index 100% rename from doc/images/DataSourceSettings.png rename to docs/images/DataSourceSettings.png diff --git a/doc/images/DatatypeTransformationsInGrafana.png b/docs/images/DatatypeTransformationsInGrafana.png similarity index 100% rename from doc/images/DatatypeTransformationsInGrafana.png rename to docs/images/DatatypeTransformationsInGrafana.png diff --git a/doc/images/FinalVisualizationWithMultipleFlightAscents.png b/docs/images/FinalVisualizationWithMultipleFlightAscents.png similarity index 100% rename from doc/images/FinalVisualizationWithMultipleFlightAscents.png rename to docs/images/FinalVisualizationWithMultipleFlightAscents.png diff --git a/doc/images/FlightDashboard_final_visualization.png b/docs/images/FlightDashboard_final_visualization.png similarity index 100% rename from doc/images/FlightDashboard_final_visualization.png rename to docs/images/FlightDashboard_final_visualization.png diff --git a/doc/images/FlightTrajSampleTable.png b/docs/images/FlightTrajSampleTable.png similarity index 100% rename from doc/images/FlightTrajSampleTable.png rename to docs/images/FlightTrajSampleTable.png diff --git a/doc/images/FrequencyIntersectingWithGeometricEnvelopVisualization.png b/docs/images/FrequencyIntersectingWithGeometricEnvelopVisualization.png similarity index 100% rename from doc/images/FrequencyIntersectingWithGeometricEnvelopVisualization.png rename to docs/images/FrequencyIntersectingWithGeometricEnvelopVisualization.png diff --git a/doc/images/FullDashboard.png b/docs/images/FullDashboard.png similarity index 100% rename from doc/images/FullDashboard.png rename to docs/images/FullDashboard.png diff --git a/doc/images/GrafanaTimerangePanelOpen.png b/docs/images/GrafanaTimerangePanelOpen.png similarity index 100% rename from doc/images/GrafanaTimerangePanelOpen.png rename to docs/images/GrafanaTimerangePanelOpen.png diff --git a/doc/images/IndividualShipSpeedStatisticsVisualization.png b/docs/images/IndividualShipSpeedStatisticsVisualization.png similarity index 100% rename from doc/images/IndividualShipSpeedStatisticsVisualization.png rename to docs/images/IndividualShipSpeedStatisticsVisualization.png diff --git a/doc/images/LocationHistory.png b/docs/images/LocationHistory.png similarity index 100% rename from doc/images/LocationHistory.png rename to docs/images/LocationHistory.png diff --git a/doc/images/MultipleLayersInDataLayersDialogueBox.png b/docs/images/MultipleLayersInDataLayersDialogueBox.png similarity index 100% rename from doc/images/MultipleLayersInDataLayersDialogueBox.png rename to docs/images/MultipleLayersInDataLayersDialogueBox.png diff --git a/doc/images/MultipleQueriesSingleVisualization.png b/docs/images/MultipleQueriesSingleVisualization.png similarity index 100% rename from doc/images/MultipleQueriesSingleVisualization.png rename to docs/images/MultipleQueriesSingleVisualization.png diff --git a/doc/images/MultipleResultsForTheSameShipAtVariousTimesWhileInAPort.png b/docs/images/MultipleResultsForTheSameShipAtVariousTimesWhileInAPort.png similarity index 100% rename from doc/images/MultipleResultsForTheSameShipAtVariousTimesWhileInAPort.png rename to docs/images/MultipleResultsForTheSameShipAtVariousTimesWhileInAPort.png diff --git a/doc/images/OverrideOptionsMultipleQueries.png b/docs/images/OverrideOptionsMultipleQueries.png similarity index 100% rename from doc/images/OverrideOptionsMultipleQueries.png rename to docs/images/OverrideOptionsMultipleQueries.png diff --git a/doc/images/RouteUsageFrequencyHeatMapVisualization.png b/docs/images/RouteUsageFrequencyHeatMapVisualization.png similarity index 100% rename from doc/images/RouteUsageFrequencyHeatMapVisualization.png rename to docs/images/RouteUsageFrequencyHeatMapVisualization.png diff --git a/doc/images/SelectingVariablesInDashboardSettings.png b/docs/images/SelectingVariablesInDashboardSettings.png similarity index 100% rename from doc/images/SelectingVariablesInDashboardSettings.png rename to docs/images/SelectingVariablesInDashboardSettings.png diff --git a/doc/images/SettingInitialViewInMapViewDialogueBox.png b/docs/images/SettingInitialViewInMapViewDialogueBox.png similarity index 100% rename from doc/images/SettingInitialViewInMapViewDialogueBox.png rename to docs/images/SettingInitialViewInMapViewDialogueBox.png diff --git a/doc/images/SettingUpHeatMapInDataLayerDialogueBox.png b/docs/images/SettingUpHeatMapInDataLayerDialogueBox.png similarity index 100% rename from doc/images/SettingUpHeatMapInDataLayerDialogueBox.png rename to docs/images/SettingUpHeatMapInDataLayerDialogueBox.png diff --git a/doc/images/SingleAirframeAltitudeVsTime.png b/docs/images/SingleAirframeAltitudeVsTime.png similarity index 100% rename from doc/images/SingleAirframeAltitudeVsTime.png rename to docs/images/SingleAirframeAltitudeVsTime.png diff --git a/doc/images/SingleAirframeCallsignVsTime.png b/docs/images/SingleAirframeCallsignVsTime.png similarity index 100% rename from doc/images/SingleAirframeCallsignVsTime.png rename to docs/images/SingleAirframeCallsignVsTime.png diff --git a/doc/images/SingleAirframeGeopointsVsTime.png b/docs/images/SingleAirframeGeopointsVsTime.png similarity index 100% rename from doc/images/SingleAirframeGeopointsVsTime.png rename to docs/images/SingleAirframeGeopointsVsTime.png diff --git a/doc/images/SingleAirframeRow1.png b/docs/images/SingleAirframeRow1.png similarity index 100% rename from doc/images/SingleAirframeRow1.png rename to docs/images/SingleAirframeRow1.png diff --git a/doc/images/SingleAirframeTrajTable.png b/docs/images/SingleAirframeTrajTable.png similarity index 100% rename from doc/images/SingleAirframeTrajTable.png rename to docs/images/SingleAirframeTrajTable.png diff --git a/doc/images/SingleAirframeVelocityVsTime.png b/docs/images/SingleAirframeVelocityVsTime.png similarity index 100% rename from doc/images/SingleAirframeVelocityVsTime.png rename to docs/images/SingleAirframeVelocityVsTime.png diff --git a/doc/images/SingleAirframeVertrateVsTime.png b/docs/images/SingleAirframeVertrateVsTime.png similarity index 100% rename from doc/images/SingleAirframeVertrateVsTime.png rename to docs/images/SingleAirframeVertrateVsTime.png diff --git a/doc/images/StandardOptionsDialogueBox.png b/docs/images/StandardOptionsDialogueBox.png similarity index 100% rename from doc/images/StandardOptionsDialogueBox.png rename to docs/images/StandardOptionsDialogueBox.png diff --git a/doc/images/StatStylesDialogueBox.png b/docs/images/StatStylesDialogueBox.png similarity index 100% rename from doc/images/StatStylesDialogueBox.png rename to docs/images/StatStylesDialogueBox.png diff --git a/doc/images/StatisticVisualizationByFlightType.png b/docs/images/StatisticVisualizationByFlightType.png similarity index 100% rename from doc/images/StatisticVisualizationByFlightType.png rename to docs/images/StatisticVisualizationByFlightType.png diff --git a/doc/images/ThresholdsDialogueBox.png b/docs/images/ThresholdsDialogueBox.png similarity index 100% rename from doc/images/ThresholdsDialogueBox.png rename to docs/images/ThresholdsDialogueBox.png diff --git a/doc/images/ValueOptionsDialogueBox.png b/docs/images/ValueOptionsDialogueBox.png similarity index 100% rename from doc/images/ValueOptionsDialogueBox.png rename to docs/images/ValueOptionsDialogueBox.png diff --git a/doc/images/VisualizationOfGeometryIntersectionUsingDynamicVariables.png b/docs/images/VisualizationOfGeometryIntersectionUsingDynamicVariables.png similarity index 100% rename from doc/images/VisualizationOfGeometryIntersectionUsingDynamicVariables.png rename to docs/images/VisualizationOfGeometryIntersectionUsingDynamicVariables.png diff --git a/doc/images/VisualizationOfShipsWithin300mUsingHeatMap.png b/docs/images/VisualizationOfShipsWithin300mUsingHeatMap.png similarity index 100% rename from doc/images/VisualizationOfShipsWithin300mUsingHeatMap.png rename to docs/images/VisualizationOfShipsWithin300mUsingHeatMap.png diff --git a/doc/images/ZoomedInViewOfFlightAscent.png b/docs/images/ZoomedInViewOfFlightAscent.png similarity index 100% rename from doc/images/ZoomedInViewOfFlightAscent.png rename to docs/images/ZoomedInViewOfFlightAscent.png diff --git a/doc/images/approach1.png b/docs/images/approach1.png similarity index 100% rename from doc/images/approach1.png rename to docs/images/approach1.png diff --git a/doc/images/approach2.png b/docs/images/approach2.png similarity index 100% rename from doc/images/approach2.png rename to docs/images/approach2.png diff --git a/doc/images/mobilitydb-logo.png b/docs/images/mobilitydb-logo.png similarity index 100% rename from doc/images/mobilitydb-logo.png rename to docs/images/mobilitydb-logo.png diff --git a/doc/images/points.png b/docs/images/points.png similarity index 100% rename from doc/images/points.png rename to docs/images/points.png diff --git a/doc/images/stib.png b/docs/images/stib.png similarity index 100% rename from doc/images/stib.png rename to docs/images/stib.png diff --git a/doc/images/trajApproach.png b/docs/images/trajApproach.png similarity index 100% rename from doc/images/trajApproach.png rename to docs/images/trajApproach.png diff --git a/doc/images/trajFerries.png b/docs/images/trajFerries.png similarity index 100% rename from doc/images/trajFerries.png rename to docs/images/trajFerries.png diff --git a/doc/images/trajFerry.png b/docs/images/trajFerry.png similarity index 100% rename from doc/images/trajFerry.png rename to docs/images/trajFerry.png diff --git a/doc/images/trajs.png b/docs/images/trajs.png similarity index 100% rename from doc/images/trajs.png rename to docs/images/trajs.png diff --git a/doc/images/trajsFiltered.png b/docs/images/trajsFiltered.png similarity index 100% rename from doc/images/trajsFiltered.png rename to docs/images/trajsFiltered.png diff --git a/doc/images/trajsShort.png b/docs/images/trajsShort.png similarity index 100% rename from doc/images/trajsShort.png rename to docs/images/trajsShort.png diff --git a/doc/images/trajsWrongAzimuth.png b/docs/images/trajsWrongAzimuth.png similarity index 100% rename from doc/images/trajsWrongAzimuth.png rename to docs/images/trajsWrongAzimuth.png diff --git a/doc/images/trajsWrongSpeed.png b/docs/images/trajsWrongSpeed.png similarity index 100% rename from doc/images/trajsWrongSpeed.png rename to docs/images/trajsWrongSpeed.png diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..18d3df3 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,14 @@ +MobilityDB icon + +----------------------------------------------- +# **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 b/docs/install.sh similarity index 100% rename from doc/install.sh rename to docs/install.sh diff --git a/doc/location_history.xml b/docs/location_history.xml similarity index 100% rename from doc/location_history.xml rename to docs/location_history.xml diff --git a/doc/mobilitydb-workshop.xml b/docs/mobilitydb-workshop.xml similarity index 100% rename from doc/mobilitydb-workshop.xml rename to docs/mobilitydb-workshop.xml diff --git a/doc/texstyle.sty b/docs/texstyle.sty similarity index 100% rename from doc/texstyle.sty rename to docs/texstyle.sty