Use mkdocs-material for Zarr-Python documentation (#3118)

* Use mkdocs-material for Zarr-Python documentation

* Update towncrier instructions

* Update readthedocs config

* Remove conda section

* Install hatch for rtd

* Move build step

* Start a shell with hatch

* Use commands

* Don't use hatch

* Figure out redirects later

* Format docstrings with ruff

* git ignore docs output

* Specify towncrier start

* Add redirects

* Don't use version extra

* Convert changes to markdown

* Use cards on homepage for now

* Execute examples in quickstart

* Execute examples in array user guide

* Auto-doc for some modules

* Cleanup quickstart

* Filter warnings in quickstart

* Add links to quickstart

* Add index pages

* Remove $ from console

* Update code block formatting for arrays

* Add cross-references to arrays

* Executable blocks and cross-references in groups user guide

* Fix links

* Executable code blocks in attrs user-guide

* Add external inventories

* Add cross-references to storage

* Executable storage guide

* Executable config code blocks

* Update V3 migration links

* Executable code blocks in data types

* Executable code blocks in performance

* Use mkdocs build --strict rather than doctest

* Executable code blocks in consolidated metadata

* Better pprint

* Add buffer protocol to API

* Cross-references in extending

* References in gpu guide

* References in gpu guide

* Fix indentation

* Formatting

* Add new release notes

* Inherit docstrings

* Add buffer API page

* Fix some links

* Update changelog check

* Update dependency

* Update cross-references

* Add cross-reference

* Convert references and admonitions

* Improve numpy dtype cross-references

* Show source

* Update changelog entries to markdown

* Strict RTD build

* Fix numpydoc errors

* Allow related section

* Update numpydoc validation config

* Fix docstring failures

* Update config ref

Author: maxrjones

.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()