Merge pull request #192 from bas-amop/dw/materialdocs

Change docs theme to material

Author: davidwyld

.github/workflows/docs.yml

@@ -26,7 +26,8 @@ jobs:
       - name: Install dependencies 🛠️
         run: |
           python -m pip install --upgrade pip
-          python -m pip install mkdocs mkdocs-autoapi mkdocs-include-markdown-plugin mkdocstrings[python] mkdocs-render-swagger-plugin
+          python -m pip install .
+          python -m pip install --group docs
       - name: Build docs 📖
         run: mkdocs build
       - name: Deploy docs 🚀

mkdocs.yml

@@ -1,11 +1,49 @@
 site_name: PolarRoute-Server
 repo_url: https://github.com/bas-amop/polarroute-server/
 edit_uri: edit/main/docs/
-theme: readthedocs
+theme: 
+  name: material
+  logo: https://cdn.web.bas.ac.uk/bas-style-kit/0.7.3/img/logos-symbols/bas-roundel-inverse-transparent-64.png
+  favicon: https://cdn.web.bas.ac.uk/bas-style-kit/0.7.3/img/favicon/favicon-16x16.png
+  icon:
+    repo: fontawesome/brands/github
+  features:
+    # Enables copying of code blocks
+    - content.code.copy
+    # Enables "edit this page" to contribute to docs
+    - content.action.edit
+  palette:
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: orange
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: orange
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
 plugins: 
   - search
-  - mkdocstrings
+  - mkdocstrings:
+      handlers:
+        python:
+          paths:
+            - .
+          options:
+            docstring_style: google
+            # show_object_full_path: true
+            merge_init_into_class: true
+            show_docstring_functions: true
+            show_docstring_classes: true
+            show_source: false
   - mkdocs-autoapi:
+      autoapi_dir: .
       autoapi_ignore:
         - "manage.py"
         - "polarrouteserver/settings/*"
@@ -18,15 +56,15 @@ plugins:
         - "polarrouteserver/celery.py"
         - "polarrouteserver/urls.py"
         - "polarrouteserver/wsgi.py"
+        - "polarrouteserver/_version.py"
         - "tests/*"
       autoapi_file_patterns:
         - "*.py"
       autoapi_add_nav_entry: Python Package API Reference
   - include-markdown:
       rewrite_relative_urls: true
   - render_swagger
-markdown_extensions: 
-  - attr_list
+
 nav:
   - Home: index.md
   - vehicle-management.md
@@ -36,4 +74,18 @@ nav:
   - configuration.md
   - development.md
   - changelog.md
-  - API Reference: api.md
+  - API Reference: api.md
+
+markdown_extensions:
+  - toc:
+      permalink: True
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji # (1)!
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+
+copyright: Copyright © 2026 British Antarctic Survey

polarrouteserver/route_api/models.py

@@ -1,3 +1,5 @@
+"""Representations of database objects with the Django object relational model."""
+
 import logging
 
 from celery.result import AsyncResult
@@ -11,6 +13,8 @@
 
 
 class Mesh(models.Model):
+    "Mesh"
+
     id = models.BigAutoField(primary_key=True)
     meshiphi_version = models.CharField(max_length=60, null=True)
     md5 = models.CharField(max_length=64)
@@ -35,6 +39,8 @@ class Meta:
 
 
 class Vehicle(models.Model):
+    "Vehicle objects"
+
     # Required properties
     vessel_type = models.CharField(
         max_length=150, default=None, unique=True, primary_key=True
@@ -59,6 +65,8 @@ class Vehicle(models.Model):
 
 
 class Route(models.Model):
+    "Represents a route."
+
     requested = models.DateTimeField(default=timezone.now)
     calculated = models.DateTimeField(null=True)
     info = models.JSONField(null=True)

pyproject.toml

@@ -58,13 +58,6 @@ dev = [
 prod = [
     "gunicorn"
 ]
-docs = [
-    "mkdocs",
-    "mkdocs-autoapi",
-    "mkdocs-include-markdown-plugin",
-    "mkdocstrings[python]",
-    "mkdocs-render-swagger-plugin",
-]
 build = [
     "build"
 ]
@@ -75,6 +68,16 @@ cov-badge = [
     "coverage-badge"
 ]
 
+[dependency-groups]
+docs = [
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocs-autoapi",
+    "mkdocs-include-markdown-plugin",
+    "mkdocstrings[python]",
+    "mkdocs-render-swagger-plugin",
+]
+
 [project.scripts]
 request_route = "request_route.request_route:main"