From 4311fa7f79a626543bb75bb91365918cc479a2a9 Mon Sep 17 00:00:00 2001 From: DavUhll <126286224+DavUhll@users.noreply.github.com> Date: Mon, 29 Jan 2024 17:09:34 +0100 Subject: [PATCH] Build documentation with mkdocs (#321) --- .github/workflows/cd.yaml | 20 +++++++++++++++++ .gitignore | 2 +- README.md | 2 ++ docs/cp_docu_files.sh | 37 ++++++++++++++++++++++++++++++++ docs/requirements.txt | 2 ++ lanelet2_core/README.md | 2 +- lanelet2_examples/README.md | 4 ++-- lanelet2_io/README.md | 4 ++-- lanelet2_python/README.md | 2 +- lanelet2_routing/README.md | 2 +- lanelet2_traffic_rules/README.md | 2 +- mkdocs.yml | 29 +++++++++++++++++++++++++ 12 files changed, 99 insertions(+), 9 deletions(-) create mode 100755 docs/cp_docu_files.sh create mode 100644 docs/requirements.txt create mode 100644 mkdocs.yml diff --git a/.github/workflows/cd.yaml b/.github/workflows/cd.yaml index 95ae7fb3..e8665b84 100644 --- a/.github/workflows/cd.yaml +++ b/.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 diff --git a/.gitignore b/.gitignore index 036b772a..d61f7463 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,4 @@ *.pyc setup.py CMakeLists.txt.user - +site diff --git a/README.md b/README.md index 5f24b528..a7049829 100644 --- a/README.md +++ b/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 diff --git a/docs/cp_docu_files.sh b/docs/cp_docu_files.sh new file mode 100755 index 00000000..668cb85e --- /dev/null +++ b/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." diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..29b84636 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +mkdocs == 1.2.3 +jinja2==3.0.3 \ No newline at end of file diff --git a/lanelet2_core/README.md b/lanelet2_core/README.md index 4d96cb4e..7da004fa 100644 --- a/lanelet2_core/README.md +++ b/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 diff --git a/lanelet2_examples/README.md b/lanelet2_examples/README.md index f3ca3b1d..6cae22df 100644 --- a/lanelet2_examples/README.md +++ b/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). diff --git a/lanelet2_io/README.md b/lanelet2_io/README.md index f6f293d1..81f3b160 100644 --- a/lanelet2_io/README.md +++ b/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 diff --git a/lanelet2_python/README.md b/lanelet2_python/README.md index 91741b0b..86f79318 100644 --- a/lanelet2_python/README.md +++ b/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). diff --git a/lanelet2_routing/README.md b/lanelet2_routing/README.md index c971680c..b6a3f6f7 100644 --- a/lanelet2_routing/README.md +++ b/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* diff --git a/lanelet2_traffic_rules/README.md b/lanelet2_traffic_rules/README.md index ed6a488d..9b730ede 100644 --- a/lanelet2_traffic_rules/README.md +++ b/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`. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..edf27172 --- /dev/null +++ b/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' +