Build documentation with mkdocs (#321)

.github/workflows/cd.yaml

@@ -122,3 +122,23 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           password: ${{ secrets.PYPI_API_TOKEN }}
+
+  deploy-pages:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/master'
+    concurrency: deploy-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: set up python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+
+      - name: set up env
+        run: python -m pip install -r docs/requirements.txt
+
+      - name: copy docs to docs folder
+        run: bash docs/cp_docu_files.sh
+
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -2,4 +2,4 @@
 *.pyc
 setup.py
 CMakeLists.txt.user
-
+site

README.md

@@ -44,6 +44,8 @@ You can find more documentation in the individual packages and in doxygen commen
 - If you are interested in Lanelet2's **projections**, you will find more [here](lanelet2_projection/doc/Map_Projections_Coordinate_Systems.md).
 - To get more information on how to create valid maps, see [here](lanelet2_maps/README.md).
 
+You can also find the documentation at this [link](https://fzi-forschungszentrum-informatik.github.io/Lanelet2).
+
 ## Installation
 
 ### Within ROS

docs/cp_docu_files.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+
+# Destination directory (docs folder)
+dest_dir="docs/"
+
+# Ensure the destination directory exists
+lanelet2_core_dir="lanelet2_core"
+lanelet2_examples_dir="lanelet2_examples"
+lanelet2_io_dir="lanelet2_io"
+lanelet2_maps_dir="lanelet2_maps"
+lanelet2_matching_dir="lanelet2_matching"
+lanelet2_projection_dir="lanelet2_projection"
+lanelet2_python_dir="lanelet2_python"
+lanelet2_routing_dir="lanelet2_routing"
+lanelet2_traffic_rules_dir="lanelet2_traffic_rules"
+lanelet2_validation_dir="lanelet2_validation"
+
+cp "README.md" "$dest_dir/index.md"
+
+cp "$lanelet2_core_dir/README.md" "$dest_dir/lanelet2_core.md"
+cp -r "$lanelet2_core_dir/doc" "$dest_dir/lanelet2_core"
+
+cp "$lanelet2_examples_dir/README.md" "$dest_dir/lanelet2_examples.md"
+cp "$lanelet2_io_dir/README.md" "$dest_dir/lanelet2_io.md"
+cp "$lanelet2_maps_dir/README.md" "$dest_dir/lanelet2_maps.md"
+cp "$lanelet2_matching_dir/README.md" "$dest_dir/lanelet2_matching.md"
+cp "$lanelet2_projection_dir/README.md" "$dest_dir/lanelet2_projection.md"
+cp -r "$lanelet2_projection_dir/doc" "$dest_dir/lanelet2_projection"
+cp "$lanelet2_python_dir/README.md" "$dest_dir/lanelet2_python.md"
+
+cp "$lanelet2_routing_dir/README.md" "$dest_dir/lanelet2_routing.md"
+cp -r "$lanelet2_routing_dir/doc" "$dest_dir/lanelet2_routing"
+
+cp "$lanelet2_traffic_rules_dir/README.md" "$dest_dir/lanelet2_traffic_rules.md"
+cp "$lanelet2_validation_dir/README.md" "$dest_dir/lanelet2_validation.md"
+
+echo "Documentation files copied to the docs folder."

docs/requirements.txt

@@ -0,0 +1,2 @@
+mkdocs == 1.2.3
+jinja2==3.0.3

lanelet2_core/README.md

@@ -6,7 +6,7 @@ This package contains the core library of Lanelet2:
 - The [basic primitives](doc/LaneletPrimitives.md), including LaneletMap
 - [Geometry functions](doc/GeometryPrimer.md)
 
-For usage examples, please refer to the [lanelet2_examples](../lanelet2_examples/README.md) package.
+For usage examples, please refer to the [lanelet2_examples](https://github.com/fzi-forschungszentrum-informatik/Lanelet2/tree/master/lanelet2_examples/README.md) package.
 
 ## Debugging
 

lanelet2_examples/README.md

@@ -2,7 +2,7 @@
 
 This package contains executable usage examples for people who would like to know how to work with a lanelet2 map. Simply look at the code in the individual lessons. They are equipped with lots of explaining comments. You can also build and run them to see them in action.
 
-The examples are divided into individual lessons that help you step by step to understand lanelet2. Simply look [here](src) for an overview on the C++ tutorials.
+The examples are divided into individual lessons that help you step by step to understand lanelet2. Simply look [here](https://github.com/fzi-forschungszentrum-informatik/Lanelet2/tree/master/lanelet2_examples/src) for an overview on the C++ tutorials.
 
-The python tutorials are shorter and demonstrate the similarity of the interface. They can be found [here](scripts/tutorial.py).
+The python tutorials are shorter and demonstrate the similarity of the interface. They can be found [here](https://github.com/fzi-forschungszentrum-informatik/Lanelet2/tree/master/lanelet2_examples/scripts/tutorial.py).
 

lanelet2_io/README.md

@@ -5,7 +5,7 @@ IO Module for parsing and writing LaneletMaps.
 It contains a various reader/writer functions for different formats. Which format will be used is determined the extension of the given filename. If a writer/parser is registered for this extension, it will be chosen automatically.
 
 Currently available IO modules are:
-- **OSM (.osm)** writes/loads specialized lanelet maps from OpenStreetMap html files. See [maps module](../lanelet2_maps/README.md) for a primer on this.
+- **OSM (.osm)** writes/loads specialized lanelet maps from OpenStreetMap html files. See [maps module](https://github.com/fzi-forschungszentrum-informatik/Lanelet2/tree/master/lanelet2_maps/README.md) for a primer on this.
 - **Binary (.bin)** writes/loads the map to/from an internal bin format. Very efficient for writing and reading but not human-readable
 
 
@@ -14,7 +14,7 @@ Most IO modules require a projection from WGS84 (lat/lon) to a local metric coor
 
 The origin should be as close to where the map is as possible.
 
-For an overview on projections, have a look at the [projection module](../lanelet2_projection/README.md).
+For an overview on projections, have a look at the [projection module](https://github.com/fzi-forschungszentrum-informatik/Lanelet2/tree/master/lanelet2_projection/README.md).
 
 
 ## Usage

lanelet2_python/README.md

@@ -15,4 +15,4 @@ for elem in map.laneletLayer:
         elem.attributes["participant:vehicle"] = "no"
 ```
 
-For more usage examples refer to our [example package](../lanelet2_examples/README.md).
+For more usage examples refer to our [example package](https://github.com/fzi-forschungszentrum-informatik/Lanelet2/tree/master/lanelet2_examples/README.md).

lanelet2_routing/README.md

@@ -19,7 +19,7 @@ The needed components to create a routing graph are:
 * **You can easily plug in your own routing cost calculation**
 * *Influences the prefered path*
 
-**Traffic Rules for a Specific Participant** (see [lanelet2_traffic_rules](../lanelet2_traffic_rules/README.md))
+**Traffic Rules for a Specific Participant** (see [lanelet2_traffic_rules](https://github.com/fzi-forschungszentrum-informatik/Lanelet2/tree/master/lanelet2_traffic_rules/README.md))
 * Determines which lanelets/areas are passable
 * *Influences the possible paths*
 

lanelet2_traffic_rules/README.md

@@ -18,7 +18,7 @@ lanelet::traffic_rules::SpeedLimitInformation speedLimit = trafficRulesPtr->spee
 
 This package offers the abstract `TrafficRules` class that is used as an interface to interpret the data in the map. It provides information whether a lanelet is usable/drivable, where lane changes are possible and what the speed limits are.
 
-Derived from this is the abstract `GenericTrafficRules` class that implements the traffic rules based on the [tagging specification](../lanelet2_core/doc). This class can then be derived to create traffic rules for individual countries and participants. This is especially important for the speed limits and interpreting country specific traffic signs.
+Derived from this is the abstract `GenericTrafficRules` class that implements the traffic rules based on the [tagging specification](https://github.com/fzi-forschungszentrum-informatik/Lanelet2/tree/master/lanelet2_core/doc). This class can then be derived to create traffic rules for individual countries and participants. This is especially important for the speed limits and interpreting country specific traffic signs.
 
 After registering this class using `RegisterTrafficRules`, Lanelet2 is able to create instances of this traffic rule using the `TrafficRuleFactory`.
 

mkdocs.yml

@@ -0,0 +1,29 @@
+site_name: Lanelet2
+repo_url: https://github.com/fzi-forschungszentrum-informatik/Lanelet2
+docs_dir: docs
+edit_uri: 'edit/master/docs/'
+theme: readthedocs
+
+nav:
+- Home: 'index.md'
+- lanelet2_core: 'lanelet2_core.md'
+- lanelet2_examples: 'lanelet2_examples.md'
+- lanelet2_io: 'lanelet2_io.md'
+- lanelet2_maps: 'lanelet2_maps.md'
+- lanelet2_matching: 'lanelet2_matching.md'
+- lanelet2_projection: 'lanelet2_projection.md'
+- lanelet2_python: 'lanelet2_python.md'
+- lanelet2_routing: 'lanelet2_routing.md'
+- lanelet2_traffic_rules: 'lanelet2_traffic_rules.md'
+- lanelet2_validation: 'lanelet2_validation.md'
+
+- Detailed Documentation:
+    - 'Architecture': 'lanelet2_core/Architecture.md'
+    - 'GeometryPrimer': 'lanelet2_core/GeometryPrimer.md'
+    - 'Lanelet1Compability': 'lanelet2_core/Lanelet1Compability.md'
+    - 'LaneletAndAreaTagging': 'lanelet2_core/LaneletAndAreaTagging.md'
+    - 'LaneletPrimitives': 'lanelet2_core/LaneletPrimitives.md'
+    - 'LinestringTagging': 'lanelet2_core/LinestringTagging.md'
+    - 'RegulatoryElementTagging': 'lanelet2_core/RegulatoryElementTagging.md'
+    - 'Map_Projections_Coordinate_Systems': 'lanelet2_projection/Map_Projections_Coordinate_Systems.md'
+