Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Build documentation with mkdocs #321

Merged
merged 5 commits into from
Jan 29, 2024
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .github/workflows/cd.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@
*.pyc
setup.py
CMakeLists.txt.user

site
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
DavUhll marked this conversation as resolved.
Show resolved Hide resolved

## Installation

### Within ROS
Expand Down
37 changes: 37 additions & 0 deletions docs/cp_docu_files.sh
Original file line number Diff line number Diff line change
@@ -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."
2 changes: 2 additions & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
mkdocs == 1.2.3
jinja2==3.0.3
2 changes: 1 addition & 1 deletion lanelet2_core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions lanelet2_examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

4 changes: 2 additions & 2 deletions lanelet2_io/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion lanelet2_python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
2 changes: 1 addition & 1 deletion lanelet2_routing/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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*

Expand Down
2 changes: 1 addition & 1 deletion lanelet2_traffic_rules/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down
29 changes: 29 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -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'