Replace Sphinx docs with MkDocs Material

.github/workflows/docs.yaml

@@ -0,0 +1,53 @@
+name: Documentation
+
+on:
+  push:
+  pull_request:
+    branches:
+      - '**'
+
+permissions: {}
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
+        with:
+          python-version: '3.14'
+          cache: 'pip'
+      - name: Install documentation dependencies
+        run: make docs-install
+      - name: Build documentation
+        run: make docs-build
+      - name: Upload Pages artifact
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
+        with:
+          path: site
+
+  deploy:
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.gitignore

@@ -11,6 +11,7 @@ build
 cover
 dist
 docs/_build
+site/
 lib/PyLD.egg-info
 profiler
 tests/test_caching.py

AGENTS.md

@@ -1,6 +1,6 @@
 # Agent guidelines
 
-Read [CONTRIBUTING.rst](CONTRIBUTING.rst) for code style, linting (e.g. `make lint`, `make fmt`), and release process.
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for code style, linting (e.g. `make lint`, `make fmt`), and release process.
 
 ## Testing
 
@@ -10,7 +10,14 @@ Read [CONTRIBUTING.rst](CONTRIBUTING.rst) for code style, linting (e.g. `make li
 
 ## Documentation
 
-- When adding or promoting public top-level API exports, reflect them in the project documentation, especially the Sphinx API reference under `docs/`.
+- Put docs-specific CSS in `docs/stylesheets/extra.css` and register it via `extra_css` in `mkdocs.yml`.
+- Put runnable doc examples in `docs/examples/` and embed them with the `example()` macro in `docs_macros.py`.
+- One page = one idea — do not combine unrelated topics on a single doc page.
+- Python object names in docs must always use backticks — in prose, headings, and card link text (not `__bold__`).
+- Doc examples must not use `set_document_loader()`; pass `documentLoader` per operation via `options`.
+- Do not use or mention function-based document loaders (`requests_document_loader`, `aiohttp_document_loader`, or plain callables) in docs; use `*DocumentLoader` classes or a `DocumentLoader` subclass.
+- Doc page H1 headers should use icons that match their card icons (e.g. `# :material-cloud-download: \`RequestsDocumentLoader\``).
+- Custom document-loader docs should illustrate subclassing `DocumentLoader`, not a bare callable.
 
 ## Committing
 

CHANGELOG.md

@@ -39,6 +39,9 @@
 - The `pytest` test runner now uses plain assert result == expect instead 
   of printing EXPECTED / ACTUAL and raising a generic failure. This enables 
   `pytests`'s native result comparison.
+- Convert `./README.rst` and `./CONTRIBUTING.rst` (reStructuredText) to 
+  `./README.md` and `./CONTRIBUTING.md` (markdown). Also update their 
+  contents to reflect the current state of the repo.
 
 ### Added
 - `pyld.DocumentLoader` abstract base class for class-based document loaders,
@@ -287,7 +290,7 @@
 - **1.0.0**!
 - [Semantic Versioning](https://semver.org/) is now past the "initial
   development" 0.x.y stage (after 6+ years!).
-- [Conformance](README.rst#conformance):
+- [Conformance](README.md#conformance):
   - JSON-LD 1.0 + JSON-LD 1.0 errata
   - JSON-LD 1.1 drafts
 - Thanks to the JSON-LD and related communities and the many many people over

CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to PyLD
+
+Want to contribute to PyLD? Great! Here are a few notes:
+
+## Code
+
+* In general, follow the common [PEP 8 Style Guide](https://www.python.org/dev/peps/pep-0008/).
+* Try to make the code pass [ruff](https://docs.astral.sh/ruff/) checks.
+
+  * `make lint` or `ruff check lib/pyld/*`
+  * You can also apply automatic fixing and formatting 
+    using `make fmt`
+
+* Use version `X.Y.Z-dev` in dev mode.
+* Use version `X.Y.Z` for releases.
+
+## Documentation
+
+The public documentation site is built with MkDocs Material.
+
+* Install documentation dependencies:
+
+  * `make docs-install`
+
+* Build the site:
+
+  * `make docs-build`
+
+* Preview documentation locally:
+
+  * `make docs-serve` (override port with `PORT=8008 make docs-serve`)
+
+* Refresh bundled JSON-LD context files:
+
+  * `make download-bundled-contexts`
+
+## Versioning
+
+* Follow the [Semantic Versioning](https://semver.org/) guidelines.
+
+## Release Process
+
+* `$EDITOR CHANGELOG.md`: update CHANGELOG with new notes, version, and date.
+* commit changes
+* `$EDITOR lib/pyld/__about__.py`: update to release version and remove `-dev` suffix.
+* `git commit CHANGELOG.md lib/pyld/__about__.py -m "Release {version}."`
+* `git tag {version}`
+* `$EDITOR lib/pyld/__about__.py`: update to next version and add `-dev` suffix.
+* `git commit lib/pyld/__about__.py -m "Start {next-version}."`
+* `git push --tags`
+
+To ensure a clean [package](https://pypi.org/project/PyLD/) upload to [PyPI](https://pypi.org/),
+use a clean checkout, and run the following:
+
+* For more info, look at the packaging 
+  [guide](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/).
+* Setup an [API token](https://pypi.org/help/#apitoken). Recommend using a
+  specific "PyLD" token and set it up as a "repository" in your
+  [`~/.pypirc`](https://packaging.python.org/en/latest/specifications/pypirc/)
+  for use in the upload command.
+* The below builds and uploads a sdist and wheel. Adjust as needed depending
+  on how you manage and clean "dist/" dir files.
+* `git checkout {version}`
+* `python3 -m build`
+* `twine check dist/*`
+* `twine upload -r PyLD dist/*`
+
+## Implementation Report Process
+
+As of early 2020, the process to generate an EARL report for the official 
+[JSON-LD Processor Conformance](https://w3c.github.io/json-ld-api/reports/) page is:
+
+* Run the tests on the `json-ld-api` and `json-ld-framing` test repos to
+  generate a `.jsonld` test report as explained in [README.md](./README.md#tests)
+* Use the [rdf](https://rubygems.org/gems/rdf) tool to generate a `.ttl`:
+
+  * `rdf serialize pyld-earl.jsonld --output-format turtle -o pyld-earl.ttl`
+
+* Optionally follow the [report instructions](https://github.com/w3c/json-ld-api/tree/master/reports) to generate the HTML report for inspection.
+* Submit a PR to the [json-ld-api repository](https://github.com/w3c/json-ld-api/pulls) with at least the `.ttl`.

MANIFEST.in

@@ -1,2 +1,2 @@
-include README.rst README.txt LICENSE CHANGELOG.md
+include README.md README.txt LICENSE CHANGELOG.md
 recursive-include lib/pyld/documentloader/frozen/bundled *.jsonld

Makefile

@@ -1,18 +1,30 @@
-.PHONY: install test upgrade-submodules download-bundled-contexts
+.PHONY: install test docs-install docs-build docs-serve upgrade-submodules download-bundled-contexts
+
+PORT ?= 8000
 
 install:
 	pip install -e .
 
 test:
 	pytest --cov=pyld
 
+docs-install:
+	python -m pip install --upgrade pip
+	pip install -r docs/requirements.txt
+
+docs-build:
+	mkdocs build --strict
+
+docs-serve:
+	mkdocs serve --dev-addr 127.0.0.1:$(PORT)
+
 upgrade-submodules:
 	git submodule update --remote --init --recursive
 
 download-bundled-contexts:
 	python scripts/download_contexts.py
 
-RUFF_TARGET = lib/pyld/*.py tests/*.py
+RUFF_TARGET = lib/pyld/*.py tests/*.py docs_macros.py
 
 lint:
 	ruff check $(RUFF_TARGET)