Use mkdocs-material for Zarr-Python documentation

.github/PULL_REQUEST_TEMPLATE.md

@@ -3,7 +3,7 @@
 TODO:
 * [ ] Add unit tests and/or doctests in docstrings
 * [ ] Add docstrings and API docs for any new/modified user-facing classes and functions
-* [ ] New/modified features documented in `docs/user-guide/*.rst`
+* [ ] New/modified features documented in `docs/user-guide/*.md`
 * [ ] Changes documented as a new file in `changes/`
 * [ ] GitHub Actions have all passed
 * [ ] Test coverage is 100% (Codecov passes)

.github/labeler.yml

@@ -1,4 +1,4 @@
 needs release notes:
   - all:
     - changed-files:
-      - all-globs-to-all-files: '!changes/*.rst'
+      - all-globs-to-all-files: '!changes/*.md'

.github/workflows/test.yml

@@ -129,11 +129,11 @@ jobs:
         pip install hatch
     - name: Set Up Hatch Env
       run: |
-        hatch env create doctest
-        hatch env run -e doctest list-env
+        hatch env create docs
+        hatch env run -e docs list-env
     - name: Run Tests
       run: |
-        hatch env run --env doctest run
+        hatch env run --env docs check
 
   test-complete:
     name: Test complete

.gitignore

@@ -49,9 +49,9 @@ coverage.xml
 # Django stuff:
 *.log
 
-# Sphinx documentation
+# Documentation
+site/
 docs/_build/
-docs/api
 docs/data
 data
 data.zip

.pre-commit-config.yaml

@@ -20,6 +20,7 @@ repos:
     rev: v6.0.0
     hooks:
       - id: check-yaml
+        exclude: mkdocs.yml
       - id: trailing-whitespace
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.17.1

.readthedocs.yaml

@@ -11,16 +11,16 @@ build:
         then
           towncrier build --version Unreleased --yes;
         fi
-
-sphinx:
-  configuration: docs/conf.py
-  fail_on_warning: true
-
-formats: all
+    build:
+        html:
+          - mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html
+mkdocs:
+  configuration: mkdocs.yml
 
 python:
    install:
    - method: pip
      path: .
      extra_requirements:
         - docs
+        - remote

changes/README.md

@@ -1,7 +1,7 @@
 Writing a changelog entry
 -------------------------
 
-Please put a new file in this directory named `xxxx.<type>.rst`, where
+Please put a new file in this directory named `xxxx.<type>.md`, where
 
 - `xxxx` is the pull request number associated with this entry
 - `<type>` is one of:

ci/check_changelog_entries.py

@@ -25,13 +25,13 @@ def is_int(s: str) -> bool:
     print(f"Found {len(entries)} entries")
     print()
 
-    bad_suffix = [e for e in entries if e.suffix != ".rst"]
+    bad_suffix = [e for e in entries if e.suffix != ".md"]
     bad_issue_no = [e for e in entries if not is_int(e.name.split(".")[0])]
     bad_type = [e for e in entries if e.name.split(".")[1] not in VALID_CHANGELOG_TYPES]
 
     if len(bad_suffix) or len(bad_issue_no) or len(bad_type):
         if len(bad_suffix):
-            print("Changelog entries without .rst suffix")
+            print("Changelog entries without .md suffix")
             print("-------------------------------------")
             print("\n".join([p.name for p in bad_suffix]))
             print()