Migrate docs to mkdocs

Author: euronion

.github/pull_request_template.md

@@ -5,7 +5,7 @@ Closes # (if applicable).
 
 ## Checklist
 
-- [ ] Code changes are sufficiently documented; i.e. new functions contain docstrings and further explanations may be given in `doc`.
+- [ ] Code changes are sufficiently documented; i.e. new functions contain docstrings and further explanations may be given in `docs`.
 - [ ] Unit tests for new features were added (if applicable).
-- [ ] A note for the release notes `doc/release_notes.rst` of the upcoming release is included.
+- [ ] A note for the release notes `doc/release_notes.md` of the upcoming release is included.
 - [ ] I consent to the release of this PR's code under the MIT license and have added my name to the `doc/contributors.md`.

.pre-commit-config.yaml

@@ -9,6 +9,7 @@ repos:
     rev: v5.0.0
     hooks:
     -   id: check-yaml
+        args: ['--unsafe'] # required for mkdocs.yaml -> pymdownx.emoji (see https://github.com/pre-commit/pre-commit-hooks/issues/552)
     -   id: end-of-file-fixer
     -   id: trailing-whitespace
     -   id: check-merge-conflict

.readthedocs.yaml

@@ -9,16 +9,20 @@
 
 version: 2
 
-build:
-  os: ubuntu-22.04
-  tools:
-    python: "3.11"
 
+mkdocs:
+  configuration: mkdocs.yaml
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: doc/conf.py
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
 
+  jobs:
+    pre_system_dependencies:
+    - git fetch --unshallow   # Needed to get version tags
+    pre_install:
+    - pip install mkdocs-material
 
 python:
   install:

README.md

@@ -104,10 +104,13 @@ and/or the current release stored on Zenodo with a release-specific DOI:
 ## Licence
 
 `powerplantmatching` is released as free software under the [MIT](LICENSES/MIT.txt) license.
-The default output data generated by the package is released under [CC BY 4.0](LICENSES/CC-BY-4.0.txt).
-Parts of the repository may be licensed under different licenses, please see the header information of the respective files and [REUSE.toml](REUSE.toml) for details.
+The default output data [powerplants.csv](powerplants.csv) generated by the package is released under [CC BY 4.0](LICENSES/CC-BY-4.0.txt).
+Parts of the repository may be licensed under different licenses, especially dependent package binaries for `duke` being licensed under [Apache 2.0 license](https://github.com/PyPSA/powerplantmatching/tree/master/LICENSES/Apache-2.0.txt).
 
 This repository uses the [REUSE](https://reuse.software/) conventions to indicate the licenses that apply to individual files and parts of the repository.
+For details on the licenses that apply, see the the header information of the respective files and [REUSE.toml](REUSE.toml) for details.
 
-(c) Contributors to powerplantmatching <https://github.com/pypsa/powerplantmatching>
-You can find a list of contributors in the [contributors page](https://github.com/PyPSA/powerplantmatching/graphs/contributors).
+Copyright 2018-2024 Fabian Gotzens (FZ Jülich), Jonas Hörsch (KIT), Fabian Hofmann (FIAS)
+Copyright 2025- Contributors to powerplantmatching <https://github.com/pypsa/powerplantmatching>
+
+You can find a list of contributors in the [contributors page](https://github.com/PyPSA/powerplantmatching/graphs/contributors) and in the [contributors file](docs/contributors.md).

REUSE.toml

@@ -6,7 +6,8 @@ SPDX-PackageDownloadLocation = "https://github.com/pypsa/powerplantmatching"
 [[annotations]]
 path = [
     "powerplants.csv",
-    "doc/**",
+    "docs/assets/images/powerplants.png",
+    "docs/examples/example.ipynb",
 ]
 SPDX-FileCopyrightText = "Contributors to powerplantmatching <https://github.com/pypsa/powerplantmatching>"
 SPDX-License-Identifier = "CC-BY-4.0"

docs/Makefile

@@ -0,0 +1,13 @@
+<!--
+SPDX-FileCopyrightText: 2025 Contributors to powerplantmatching <https://github.com/pypsa/powerplantmatching>
+
+SPDX-License-Identifier: MIT
+-->
+
+# Core Modules
+
+::: powerplantmatching.core
+
+::: powerplantmatching.duke
+
+::: powerplantmatching.accessor

docs/api-core.md

@@ -0,0 +1,15 @@
+<!--
+SPDX-FileCopyrightText: 2025 Contributors to powerplantmatching <https://github.com/pypsa/powerplantmatching>
+
+SPDX-License-Identifier: MIT
+-->
+
+# Data Processing Modules
+
+::: powerplantmatching.data
+
+::: powerplantmatching.cleaning
+
+::: powerplantmatching.matching
+
+::: powerplantmatching.collection