add MkDocs (#117)

.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: 🚧 Website MkDocs
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch: # useful for testing tx pushes
+  workflow_call: # call from release
+
+defaults:
+  run:
+    working-directory: docs
+
+jobs:
+  website:
+    runs-on: ubuntu-latest
+    # Skip if this job was scheduled and the runner belongs to a fork (i.e. forks have no use for this action)
+    if: (github.event_name == 'schedule' && github.repository == 'opengisch/django-oapif') || (github.event_name != 'schedule')
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Python requirements
+        run: |
+          pip install -r requirements.txt
+          pip install -r requirements-dev.txt
+
+      - name: Build documentation
+        run: mkdocs build
+
+      - uses: actions/upload-artifact@v4
+        if: ${{ github.event_name == 'pull_request' }}
+        with:
+          name: docs
+          path: docs/site
+          if-no-files-found: error
+
+      - name: Deploy to GitHub Pages
+        if: contains(fromJSON('["push", "workflow_dispatch"]'), github.event_name)
+        run: mkdocs gh-deploy --force

.gitignore

@@ -11,9 +11,10 @@ dist
 *.egg-info
 django_oapif/core/__version__.py
 
+docs/site
+
 tests/benchmark/output
 tests/output
-
 tests/django_oapif_tests/tests/fixtures/polygon_2056.json.gz
 tests/django_oapif_tests/tests/fixtures/polygon_2056_local_geom.json.gz
 

README.md

@@ -1,108 +1,6 @@
-# django-oapif
+# Django-OAPIF
 
-**WARNING** This is in under development. API will break. Do not use in production.
+*Django-OAPIF* allows to easily expose your Django models through an OGC API Features endpoint.
+It is based on Django REST Framework.
 
-*django-oapif* allows to easily expose your Django models through an OAPI-Features endpoint. It is based on Django REST Framework.
-
-## Table of contents
-- [Quickstart](#quickstart)
-- [Use from QGIS](#use-from-qgis)
-- [Install it as a Django app](#install-it-as-a-django-app)
-- [Authentication & permissions](#custom-authentication--permissions)
-- [Tests](#tests)
-- [OGC conformance](#ogc-conformance)
-
-## Quickstart
-
-This lets you run the Compose application locally and demo it:
-
-```bash
-# copy default conf
-cp .env.example .env
-
-# start the stack
-docker compose up --build -d
-
-# deploy static files and migrate database
-docker compose exec django python manage.py collectstatic --no-input
-docker compose exec django python manage.py migrate --no-input
-
-# A convenience start-up Django command is there
-# to populate the database with testdata
-docker compose exec django python manage.py populate_users
-docker compose exec django python manage.py populate_data
-```
-After waiting little you'll be able to access all collections at http://0.0.0.0:7180/oapif/collections.
-
-Three users are provided out of the box; they can be logged in with through basic authentication; all `123` for password:
-- `demo_viewer`
-- `demo_editor`
-- `admin`
-
-As expected `admin` can access Django Admin at http://0.0.0.0:7180/admin.
-
-## Use from QGIS
-
-When up and running you can access the REST API from QGIS like this:
-
-- Go to `Layers` > `Add layer` > `Add WFS Layer...`
-- Create a new connection
-  - URL: `https://0.0.0.0:7180/oapif/`
-  - Version: `OGC API - Features`
-- Click OK and ignore choose to ignore the invalid certificate error and store the exception
-- You should see the two layers in the list, select them and choose `add`.
-
-## Install it as a Django app
-
-This project is [hosted on PyPI](https://pypi.org/project/django-oapif/). You can install it as a Django app:
-
-```bash
-# Install with your favorite package manager
-pip3 install --user https://github.com/opengisch/django-oapif
-# Edit your Django project's settings.py accordingly:
-settings.py
------------
-INSTALLED_APPS = [
-    ...
-    django_oapif
-]
-```
-## Custom authentication & permissions
-
-By default the viewsets under `tests` use the `DjangoModelPermissionsOrAnonReadOnly` permissions class. You can add model permissions when registering their corresponding viewsets, as `permission_classes` [^1]. Example:
-
-```python
-models.py
----------
-from rest_framework import permissions
-from django.contrib.gis.db import models
-from django_oapif import register_oapif_viewset
-
-
-@register_oapif_viewset(
-    custom_viewset_attrs={
-        "permission_classes": (permissions.DjangoModelPermissionsOrAnonReadOnly,)
-    }
-)
-class MyModel(models.Model):
-    ...
-```
-
-[^1]: Refer to https://www.django-rest-framework.org/api-guide/permissions/#api-reference for permission classes.
-
-## Tests
-
-To run all tests, launch the Compose application as shown in the [Quickstart](#quickstart). Then run
-
-    docker compose exec django python manage.py test
-
-
-## OGC Conformance
-
-You can run the OGC API conformance test suite like this:
-
-```
-docker compose run conformance_test
-```
-
-Results will be stored to `tests/output/emailable-report.html
+https://opengisch.github.io/django-oapif

django_oapif/README.md

@@ -1,79 +1,4 @@
-# Django OAPIF
+# Django-OAPIF
 
-This Django app implements an OGC Services API Features (a.k.a. OAPIF) for Django.
-
-It provides a Django Rest Framework (DRF) specific router to which you can
-register your Viewsets, and thus benefit from all DRF's features (permissions,
-serialization, authentication, etc.).
-
-## Quickstart
-
-1. Download Django-OAPIF: `pip install https://github.com/opengisch/django-oapif.git`
-
-2. In `settings.py` make sure that rest_framework is installed:
-
-```python
-INSTALLED_APPS = [
-    ...,
-    "django_oapif",
-    "rest_framework",
-    "rest_framework_gis",
-    ...,
-]
-
-```
-
-Add this to your `urls.py` :
-
-urlpatterns += [
-    ...,
-    path("oapif/", include(django_oapif.urls)),
-    ...,
-]
-
-3. Register your models with the decorator:
-
-```python
-# models.py
-
-from django.contrib.gis.db import models
-from django_oapif import register
-
-
-@register_oapif_viewset()
-class TestingDecorator(models.Model):
-    name = models.CharField(max_length=10)
-    geom = models.PointField(srid=2056)
-```
-
-4. Configure global settings
-
-Optionally specify your endpoint's metadata in `settings.py`:
-
-```python
-# settings.py
-...
-
-OAPIF_TITLE = "My Endpoint"
-OAPIF_DESCRIPTION = "Description"
-```
-
-Voilà ! Your OAPIF endpoint should be ready to use.
-
-## Permissions
-
-Permissions are defined by default using Django model permissions.
-
-## Advanced use cases
-
-If you need more control over the serialization or the viewset, refer to the decorator's code and to DRF's viewset documentation.
-
-## Roadmap / status
-
-This is probably still relatively far from a full OGC Services API implementation and currently only aims to support read-only view from QGIS.
-
-This app will at some point be factored out into a reusable Django library.
-
-## Releases
-
-Releases are made automatically from the CI whenever a tag in format `v*` is pushed. Please use semantic versionning for tagging releases.
+*Django-OAPIF* allows to easily expose your Django models through an OGC API Features endpoint.
+It is based on Django REST Framework.

docs/content/demo.md

@@ -0,0 +1,46 @@
+---
+hide:
+  - navigation
+---
+
+# Try the demo
+
+## Setup
+
+This lets you run the compose application locally and demo it:
+
+```bash
+# copy default conf
+cp .env.example .env
+
+# start the stack
+docker compose up --build -d
+
+# deploy static files and migrate database
+docker compose exec django python manage.py collectstatic --no-input
+docker compose exec django python manage.py migrate --no-input
+
+# A convenience start-up Django command is there
+# to populate the database with testdata
+docker compose exec django python manage.py populate_users
+docker compose exec django python manage.py populate_data
+```
+After waiting little you'll be able to access all collections at http://0.0.0.0:7180/oapif/collections.
+
+Three users are provided out of the box; they can be logged in with through basic authentication; all `123` for password:
+- `demo_viewer`
+- `demo_editor`
+- `admin`
+
+As expected `admin` can access Django Admin at http://0.0.0.0:7180/admin.
+
+## Use from QGIS
+
+When up and running you can access the REST API from QGIS like this:
+
+- Go to `Layers` > `Add layer` > `Add WFS Layer...`
+- Create a new connection
+  - URL: `https://0.0.0.0:7180/oapif/`
+  - Version: `OGC API - Features`
+- Click OK and ignore choose to ignore the invalid certificate error and store the exception
+- You should see the two layers in the list, select them and choose `add`.

docs/content/index.md

@@ -0,0 +1,9 @@
+---
+hide:
+  - navigation
+---
+
+# Django-OAPIF
+
+*Django-OAPIF* allows to easily expose your Django models through an OGC API Features endpoint.
+It is based on Django REST Framework.

docs/content/permissions.md

@@ -0,0 +1,27 @@
+---
+hide:
+  - navigation
+---
+
+# Custom authentication & permissions
+
+By default the viewsets use `DjangoModelPermissionsOrAnonReadOnly` [permissions class from DRF](https://www.django-rest-framework.org/api-guide/permissions/#djangomodelpermissionsoranonreadonly).
+
+This can be altered in the DRF settings by adapting `DEFAULT_PERMISSION_CLASSES`.
+
+You can also add custom permissions when registering their corresponding viewsets, as [`permission_classes`](https://www.django-rest-framework.org/api-guide/permissions/#api-reference).
+Example in `models.py`:
+
+```python
+from rest_framework import permissions
+from django.contrib.gis.db import models
+from django_oapif import register_oapif_viewset
+
+@register_oapif_viewset(
+    custom_viewset_attrs={
+        "permission_classes": (permissions.DjangoModelPermissionsOrAnonReadOnly,)
+    }
+)
+class MyModel(models.Model):
+    ...
+```