Migrate documentation to mkdocs

.github/workflows/docs.yml

@@ -3,48 +3,45 @@ name: Documentation
 on:
   push:
     tags:
-      - '*'
-    branches:
-      - main
-      - docs
+      - "*"
+  workflow_dispatch:
 
 jobs:
-
   documentation:
-
+    name: Build Documentation
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
 
     steps:
-
-    - uses: actions/checkout@v4
-      with:
-        persist-credentials: false
-
-    - name: Setup PHP
-      uses: shivammathur/setup-php@2.28.0
-      with:
-        php-version: 8.1
-        extensions: mbstring, dom, intl, iconv
-
-    - name: Install Dependencies
-      run: composer install --prefer-dist --no-progress --no-suggest --dev
-
-    - name: Install Daux
-      run: composer require daux/daux.io:^0.22.0 --prefer-dist --no-progress --no-suggest --dev
-
-    - name: Create Build Directory
-      run: mkdir -p build/daux
-
-    - name: Generate Documentation
-      run: vendor/bin/daux generate -d build/daux
-
-    - name: Deploy Documentation Website
-      uses: AEnterprise/rsync-deploy@v1.0.2
-      env:
-        DEPLOY_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
-        ARGS: "-e -c -r --delete"
-        SERVER_PORT: 22
-        FOLDER: "./build/daux/"
-        SERVER_IP: ${{ secrets.DOCS_REMOTE_HOST }}
-        USERNAME: ${{ secrets.DOCS_REMOTE_USER }}
-        SERVER_DESTINATION: ${{ secrets.DOCS_REMOTE_TARGET_PATH }}
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install dependencies
+        working-directory: documentation
+        run: |
+          pip install -r requirements.txt
+
+      - name: Build Documentation
+        working-directory: documentation
+        run: |
+          mkdocs build -d ../build/documentation
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.CONTAINER_REGISTRY_TOKEN }}
+
+      - name: Build and Push Docker Image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ghcr.io/mjaschen/phpgeo-documentation:latest

Dockerfile

@@ -0,0 +1,3 @@
+FROM nginx:alpine
+
+COPY build/documentation /usr/share/nginx/html

Makefile

@@ -8,17 +8,29 @@ docs: daux
 
 .PHONY: daux
 daux:
-	rm -Rf build/daux
-	mkdir -p build/daux
-	docker run --rm -v "$(PWD)":/src -w /src daux/daux.io daux generate -d build/daux
+	rm -Rf build/documentation
+	mkdir -p build/documentation
+	cd documentation && \
+		python3 -m venv .venv && \
+		. .venv/bin/activate && \
+		pip install -r requirements.txt && \
+		mkdocs build -d ../build/documentation
+
+.PHONY: serve-docs
+serve-docs:
+	cd documentation && \
+		python3 -m venv .venv && \
+		. .venv/bin/activate && \
+		pip install -r requirements.txt && \
+		mkdocs serve -f mkdocs.yml --livereload --watch docs --watch mkdocs.yml
 
 .PHONY: clean
 clean:
 	rm -Rf build
 
 .PHONY: upload_docs
 upload_docs: docs
-	rsync --recursive --delete build/daux/ $(UPLOAD_HOST):$(UPLOAD_PATH)/
+	rsync --recursive --delete build/documentation/ $(UPLOAD_HOST):$(UPLOAD_PATH)/
 
 .PHONY: ci
 ci: lint coding-standards composer-validate sniff static-analysis-psalm unit-tests

docs/010_Installation.md → documentation/docs/010_Installation.md

@@ -2,7 +2,7 @@
 
 ## Requirements
 
-Minimum required PHP version is 8.2. *phpgeo* is tested up to PHP 8.4.
+Minimum required PHP version is 8.2. *phpgeo* is tested up to PHP 8.5.
 
 New features will only go into the main branch and won't be backported.
 
@@ -13,6 +13,7 @@ Please refer to the following table for the compatibility matrix:
 
 | PHP Version | phpgeo Version |   Support Status   | Composer Install                        |
 |:-----------:|:--------------:| :----------------: | --------------------------------------- |
+|     8.5     |      6.x       |     ✅ active      | `composer require mjaschen/phpgeo`      |
 |     8.4     |      6.x       |     ✅ active      | `composer require mjaschen/phpgeo`      |
 |     8.3     |      6.x       |     ✅ active      | `composer require mjaschen/phpgeo`      |
 |     8.2     |      6.x       |     ✅ active      | `composer require mjaschen/phpgeo`      |

docs/020_Development.md → documentation/docs/020_Development.md

@@ -55,15 +55,10 @@ done
 
 ## Creating the documentation
 
-*phpgeo's* documentation is generated with [Daux](https://daux.io/) from Markdown files.
-The `Makefile` provides a helper target for generating the complete documentation:
+*phpgeo's* documentation is generated with [Material for
+MkDocs](https://squidfunk.github.io/mkdocs-material/) from Markdown files. The
+`Makefile` provides a helper target for generating the complete documentation:
 
 ``` shell
 make docs
 ```
-
-*Daux* can also be run from its official Docker image:
-
-``` shell
-docker run --rm -it -v "$(pwd)":/phpgeo -w /phpgeo daux/daux.io daux generate -d build/daux
-```

docs/100_Geometries/110_Coordinate.md → documentation/docs/100_Geometries/110_Coordinate.md

@@ -12,4 +12,4 @@ Geographic latitude and longitude values are float numbers between
 -90.0 and 90.0 (degrees latitude) and -180.0 and 180.0 (degrees longitude).
 
 The Ellipsoid is a representation of an approximated shape of the earth and
-is abstracted in its own [`Ellipsoid`](Ellipsoid) Link class.
+is abstracted in its own [`Ellipsoid`](300_Ellipsoid.md) Link class.

docs/100_Geometries/120_Line.md → documentation/docs/100_Geometries/120_Line.md

@@ -1,6 +1,5 @@
 # Line
 
-[TOC]
 
 A line consists of two points, i.e. instances of the `Coordinate` class.
 

docs/100_Geometries/130_Polyline.md → documentation/docs/100_Geometries/130_Polyline.md

@@ -1,6 +1,5 @@
 # Polyline
 
-[TOC]
 
 A polyline consists of an ordered list of locations, i.e. instances of
 the `Coordinate` class.
@@ -59,7 +58,7 @@ Segment length: 169.21 kilometers
 
 ## Length
 
-Length calculation is described in the [Distance and Length](../Calculations/Distance_and_Length) section.
+Length calculation is described in the [Distance and Length](../400_Calculations/410_Distance_and_Length.md) section.
 
 ## Average Point
 

docs/100_Geometries/140_Polygon.md → documentation/docs/100_Geometries/140_Polygon.md

@@ -1,6 +1,5 @@
 # Polygon
 
-[TOC]
 
 A polygon consists of an ordered list of locations, i.e. instances of
 the `Coordinate` class. It's very similar to a polyline, but its start
@@ -90,7 +89,7 @@ The code above will produce the output below:
 
 ## Length/Perimeter
 
-Length calculation is described in the [Distance and Length](../Calculations/Distance_and_Length) section.
+Length calculation is described in the [Distance and Length](../400_Calculations/410_Distance_and_Length.md) section.
 
 ## Area
 

docs/100_Geometries/index.md → documentation/docs/100_Geometries/index.md

@@ -2,10 +2,10 @@
 
 _phpgeo_ provides several geometry classes:
 
-* [`Coordinate`](Coordinate)
-* [`Line`](Line)
-* [`Polyline`](Polyline)
-* [`Polygon`](Polygon)
+* [`Coordinate`](110_Coordinate.md)
+* [`Line`](120_Line.md)
+* [`Polyline`](130_Polyline.md)
+* [`Polygon`](140_Polygon.md)
 
 A Coordinate represents a geographic location, i.e. it contains a latitude
 and a longitude - together with a so-called Ellipsoid.

documentation/docs/300_Comparisons/340_Intersections.md

@@ -0,0 +1,71 @@
+## Intersection Checking
+
+The `Intersection` helper checks whether two geometries intersect. It supports
+polygons, polylines, and lines, plus point-in-polygon checks.
+
+Basic usage:
+
+```php
+use Location\Coordinate;
+use Location\Intersection\Intersection;
+use Location\Line;
+use Location\Polygon;
+
+$intersection = new Intersection();
+
+$line = new Line(
+    new Coordinate(52.237594, 9.287635),
+    new Coordinate(52.258154, 11.010313)
+);
+
+$polygon = new Polygon();
+$polygon->addPoint(new Coordinate(52.56571, 9.998658));
+$polygon->addPoint(new Coordinate(52.369576, 9.560167));
+$polygon->addPoint(new Coordinate(52.102252, 9.62397));
+$polygon->addPoint(new Coordinate(51.983342, 10.132727));
+$polygon->addPoint(new Coordinate(52.083498, 10.699142));
+$polygon->addPoint(new Coordinate(52.457087, 10.590607));
+$polygon->addPoint(new Coordinate(52.56571, 9.998658));
+
+// Fast check: bounds intersection only (may return false positives).
+$intersects = $intersection->intersects($line, $polygon, false);
+
+// Precise check: segment intersections + containment.
+$intersectsPrecisely = $intersection->intersects($line, $polygon, true);
+```
+
+Point-in-polygon is also supported:
+
+```php
+use Location\Coordinate;
+use Location\Intersection\Intersection;
+use Location\Polygon;
+
+$intersection = new Intersection();
+$point = new Coordinate(52.328745, 10.151638);
+$intersects = $intersection->intersects($point, $polygon, true);
+```
+
+For point-to-point comparisons, use `Coordinate::hasSameLocation()` or
+`Coordinate::intersects()` instead of `Intersection`.
+
+The following combinations of geometries can be checked for intersection:
+
+|          | Point                                                          | Line | Polyline | Polygon                                                   |
+|----------|----------------------------------------------------------------|------|----------|-----------------------------------------------------------|
+| Point    | yes ([same location](310_Same_Point_Comparison.md))            | no   | no       | yes ([point inside polygon](../400_Calculations/440_Geofence.md)) |
+| Line     | no                                                             | yes  | yes      | yes                                                       |
+| Polyline | no                                                             | yes  | yes      | yes                                                       |
+| Polygon  | yes ([point inside polygon](../400_Calculations/440_Geofence.md)) | yes  | yes      | yes                                                       |
+
+### Precision modes
+
+`Intersection::intersects()` accepts a third parameter that controls precision:
+
+- `false` (default) checks only the geometries' bounds. This is fast but can
+  produce false positives when bounds overlap but shapes do not.
+- `true` checks each segment for intersection and also checks polygon
+  containment. This is slower but accurate for supported geometries.
+
+If you pass unsupported combinations (for example, point-to-line), an
+`InvalidGeometryException` is thrown.

docs/400_Calculations/410_Distance_and_Length.md → documentation/docs/400_Calculations/410_Distance_and_Length.md

@@ -1,6 +1,5 @@
 # Distance and Length
 
-[TOC]
 
 ## Distance Between Two Points (Vincenty's Formula)
 
@@ -77,7 +76,7 @@ The code above will produce the output below:
 length of a GPS track or a route. A polyline consists of at least two points.
 Points are instances of the `Coordinate` class.
 
-For more details about polylines/GPS tracks see the [`Polyline`](../Geometries/Polyline) section.
+For more details about polylines/GPS tracks see the [`Polyline`](../100_Geometries/130_Polyline.md) section.
 
 ``` php
 <?php

docs/400_Calculations/420_Bearing_and_Destination.md → documentation/docs/400_Calculations/420_Bearing_and_Destination.md

@@ -1,6 +1,5 @@
 # Bearing and Destination
 
-[TOC]
 
 phpgeo can be used to calculate the bearing between two points and to
 get a destination point for a given start point together with a bearing

docs/400_Calculations/425_Cardinal_Distance.md → documentation/docs/400_Calculations/425_Cardinal_Distance.md

@@ -7,7 +7,6 @@ In the following example the Cardinal Distances are labeled *N* and *E:*
 
 ![Cardinal Distance](cardinal-distance.png)
 
-[TOC]
 
 With *phpgeo* there are two ways to calculate the Cardinal Distances:
 

docs/400_Calculations/430_Perpendicular_Distance.md → documentation/docs/400_Calculations/430_Perpendicular_Distance.md

@@ -5,8 +5,8 @@ a line (in the two-dimensional plane) respectively between a point and a
 [great circle](https://en.wikipedia.org/wiki/Great_circle) on a spherical surface.
 
 With _phpgeo_ it is possible to calculate the perpendicular distance between a
-point (instance of the [`Coordinate`](../Geometries/Coordinate) class) and a
-Great Circle - which is defined by a [`Line`](../Geometries/Line). A line is
+point (instance of the [`Coordinate`](../100_Geometries/110_Coordinate.md) class) and a
+Great Circle - which is defined by a [`Line`](../100_Geometries/120_Line.md). A line is
 defined by a pair of coordinates.
 
 The distance between points *P* and *X* is the perpendicular distance in the following sketch:

docs/400_Calculations/435_Distance_Between_Point_and_Line.md → documentation/docs/400_Calculations/435_Distance_Between_Point_and_Line.md

@@ -1,8 +1,8 @@
 # Distance Between a Point and a Line
 
 It's possible to calculate the shortest distance between a point and a
-[`Line`](../Geometries/Line). As [`Polyline`](../Geometries/Polyline)
-and [`Polygon`](../Geometries/Polygon) are also built upon the `Line` class
+[`Line`](../100_Geometries/120_Line.md). As [`Polyline`](../100_Geometries/130_Polyline.md)
+and [`Polygon`](../100_Geometries/140_Polygon.md) are also built upon the `Line` class
 it's also possible to calculate distances from a point the polyline/polygon
 by iterating over their segments.
 

docs/500_Transformations_and_Processing/510_Simplifying_a_Polyline_or_Polygon.md → documentation/docs/500_Transformations_and_Processing/510_Simplifying_a_Polyline_or_Polygon.md

@@ -1,6 +1,5 @@
 # Simplifying a polyline/polygon
 
-[TOC]
 
 Polylines and polygons can be simplified to save storage space or bandwidth.