From 11b937175f6f683eabcb53c363592e7ff89aed86 Mon Sep 17 00:00:00 2001 From: David Uhl Date: Thu, 28 Sep 2023 22:03:24 +0200 Subject: [PATCH 1/5] Build documentation with mkdocs --- .gitignore | 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 +++++++++++++++++++++++++ 10 files changed, 77 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/.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/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' + From e4da0929970865b9c1fe13df1bfcfbb93ad5813b Mon Sep 17 00:00:00 2001 From: Maximilian Naumann Date: Wed, 4 Oct 2023 04:15:45 +0200 Subject: [PATCH 2/5] Update cd.yaml --- .github/workflows/cd.yaml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) 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 From 20ce48cc20bfaaa47a5ae041d6e9a02ab925611e Mon Sep 17 00:00:00 2001 From: David Uhl Date: Wed, 3 Jan 2024 15:37:39 +0100 Subject: [PATCH 3/5] Add link of documentation to readme --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 5f24b528..b665649c 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 From 8aa52d9176c129700157f2f0d5ef8a85f50e5dc2 Mon Sep 17 00:00:00 2001 From: DavUhll <126286224+DavUhll@users.noreply.github.com> Date: Fri, 5 Jan 2024 11:39:45 +0100 Subject: [PATCH 4/5] Update README.md Co-authored-by: Maximilian Naumann --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b665649c..41a06d3b 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ 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). +You can also find the documentation at this [link](https://fzi-forschungszentrum-informatik.github.io/lanelet2). ## Installation From 643a21e326410cd4f59692342c32b91180787458 Mon Sep 17 00:00:00 2001 From: immel-f <53239370+immel-f@users.noreply.github.com> Date: Mon, 15 Jan 2024 14:23:56 +0100 Subject: [PATCH 5/5] fix typo Co-authored-by: Maximilian Naumann --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 41a06d3b..a7049829 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ 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). +You can also find the documentation at this [link](https://fzi-forschungszentrum-informatik.github.io/Lanelet2). ## Installation