MobilityDB-Workshop 1.1 - documentation and docker generation

MobilityDB · Oct 4, 2023 · e3c042f · e3c042f
2 parents 29a1574 + 6dbae0a
commit e3c042f
Show file tree

Hide file tree

Showing 68 changed files with 246 additions and 6 deletions.
diff --git a/.github/workflows/docker-image.yaml b/.github/workflows/docker-image.yaml
@@ -0,0 +1,56 @@
+name: Docker image
+on:
+  push:
+    branches:
+      - '*'
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  pull_request:
+    branches:
+      - '*'
+jobs:
+  build:
+    name: Build & push docker image
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+        fail-fast: false
+        matrix:
+          psql: [15]
+          postgis: [3.4]
+          os: [ubuntu-latest]
+
+    env:
+      IMG_NAME: ${{ github.repository }}
+    steps:
+      - name: Checkout
+        uses: actions/[email protected]
+
+      - name: Info
+        run: echo "Parameters. ${{ github.event.base_ref }}, ${{ github.ref_type }}, ${{ github.ref }}"
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          platforms: linux/amd64,linux/arm64
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          platforms: linux/amd64,linux/arm64
+          context: .
+          file: ./docker/Dockerfile
+          push: true
+          tags: mobilitydb/mobilitydb:${{ matrix.psql }}-${{ matrix.postgis }}-1.0-workshop
+          build-args: |
+            POSTGRES_VERSION=${{ matrix.psql }}
+            POSTGIS_VERSION=${{ matrix.postgis }}
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/docker/Dockerfile b/docker/Dockerfile
@@ -0,0 +1,56 @@
+ARG POSTGRES_VERSION
+ARG POSTGIS_VERSION
+
+FROM postgis/postgis:$POSTGRES_VERSION-$POSTGIS_VERSION
+
+# Configuration Parameters
+LABEL maintainer="MobilityDB Project - https://github.com/MobilityDB/MobilityDB"
+ENV POSTGRES_DB=mobilitydb
+ENV POSTGRES_USER=docker
+ENV POSTGRES_PASSWORD=docker
+ENV MOBILITYDB_VERSION $MOBDB_VERSION
+
+# Fix the Release file expired problem
+RUN echo "Acquire::Check-Valid-Until \"false\";\nAcquire::Check-Date \"false\";" | cat > /etc/apt/apt.conf.d/10no--check-valid-until
+
+
+# Install Prerequisites
+RUN apt-get update \
+ && apt-get install -y \
+    build-essential \
+    cmake \
+    git \
+    libproj-dev \
+    g++ \
+    wget \
+    autoconf \
+    autotools-dev \
+    libgeos-dev \
+    libpq-dev \
+    libproj-dev \
+    libjson-c-dev \
+    protobuf-c-compiler \
+    xsltproc \
+    libgsl-dev \
+    libgslcblas0 \
+    postgresql-server-dev-${PG_MAJOR} \
+  && rm -rf /var/lib/apt/lists/*
+
+# Install MobilityDB
+RUN wget -O MobilityDB.tar.gz "https://github.com/MobilityDB/MobilityDB/archive/v1.0.tar.gz" \
+ && mkdir -p /usr/local/src/MobilityDB \
+ && tar \
+        --extract \
+        --file MobilityDB.tar.gz \
+        --directory /usr/local/src/MobilityDB \
+        --strip-components 1 \
+ && rm MobilityDB.tar.gz
+RUN mkdir /usr/local/src/MobilityDB/build
+RUN cd /usr/local/src/MobilityDB/build && \
+    cmake .. && \
+    make -j$(nproc) && \
+    make install
+
+RUN rm /docker-entrypoint-initdb.d/10_postgis.sh
+COPY ./docker/initdb-mobilitydb.sh /docker-entrypoint-initdb.d/mobilitydb.sh
+RUN chmod +x /docker-entrypoint-initdb.d/mobilitydb.sh
diff --git a/docker/initdb-mobilitydb.sh b/docker/initdb-mobilitydb.sh
@@ -0,0 +1,11 @@
+#!/bin/bash
+
+echo "shared_preload_libraries = 'postgis-3.so'" >> $PGDATA/postgresql.conf
+
+set -e
+
+# Create the 'mobilitydb' extension in the mobilitydb database
+echo "Loading MobilityDB extension into mobilitydb"
+psql --user="$POSTGRES_USER" --dbname="mobilitydb" <<- 'EOSQL'
+	CREATE EXTENSION IF NOT EXISTS mobilitydb CASCADE;
+EOSQL
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