Replace Sphinx docs with MkDocs Material by anatoly-scherbakov · Pull Request #272 · digitalbazaar/pyld

anatoly-scherbakov · 2026-06-01T18:44:31Z

Fixes #259. Documentation at https://digitalbazaar.github.io/pyld/

Summary

replace the old Sphinx docs setup with MkDocs Material
add user-facing docs pages for installation, examples, document loaders, and manual API reference
add GitHub Pages deployment workflow and local make serve target

Validation

.venv/bin/mkdocs build --strict

github-actions · 2026-06-01T18:47:34Z

Coverage Report

File	Stmts	Miss	Cover	Missing
lib/pyld
canon.py	218	4	98%	27, 180, 565–566
context_resolver.py	103	8	92%	76, 135, 149, 195, 201–203, 227
iri_resolver.py	141	3	98%	307–308, 318
jsonld.py	2444	164	93%	271–275, 356, 393, 398, 408, 425–440, 476–477, 519, 527, 547, 555–556, 664–669, 749–750, 765–766, 826–831, 856–857, 872–873, 883–884, 910, 951, 961, 967–971, 982–983, 1016, 1025, 1032, 1097, 1120, 1142–1144, 1154–1157, 1172, 1195, 1207–1210, 1302, 1314–1317, 1337, 1366, 1399, 1403, 1440, 1483, 1502–1505, 1514, 1563, 1666–1673, 1700–1702, 1728–1731, 1907, 1945, 2353, 2362–2369, 2461, 2488, 2511, 2520, 3096, 3149, 3152, 3215, 3300, 3334, 3342, 3620, 3625, 3627, 3676, 3814–3818, 3884, 3921, 3984, 4219, 4507, 4641, 4675, 4704–4707, 4733–4734, 4917, 4981, 5008, 5082, 5084, 5102, 5200, 5249, 5481, 5483, 5522, 5524, 5533, 5672, 5800, 5887, 6007–6021, 6083, 6085, 6153, 6366, 6372–6376, 6415, 6418, 6508–6509, 6518
lib/pyld/documentloader
aiohttp.py	71	22	69%	29–39, 68, 74, 86, 98–106, 118–121, 138, 153–156
requests.py	49	5	90%	54, 68, 80–88
TOTAL	3214	206	94%

Tests	Skipped	Failures	Errors	Time
1687	50 💤	0 ❌	0 🔥	2m 20s ⏱️

mielvds

Very nice and also long overdue! I added some comments, nothing major. I can think of many things to add ofc., but I'll leave these for upcoming PR's. It would be nice to include this in the next release.

mielvds · 2026-06-02T11:26:23Z

 test:
 	pytest --cov=pyld

+serve:


If you can serve the docs from make, I'd expect you can build them too (including installing the deps).

mielvds · 2026-06-02T11:27:41Z

@@ -1 +1,3 @@
-sphinx-autobuild
+-r ../requirements.txt
+mkdocs-material


I'd specify the version

mielvds · 2026-06-02T11:43:34Z

-
-PyLD is compatible with `Python`_ 2.5 and newer.
-
-Credits


Can we have a spot for this somewhere? Maybe it's time to add ourselves as current maintainers ;)

mielvds · 2026-06-02T11:46:24Z

+contexts, while keeping the document shape practical for web APIs, JavaScript,
+and JSON document stores.
+
+## Conformance


While not really in scope, I'd align these updates with README.rst to not let things drift (this is long overdue as well, because it still talks about candidate recommendation). Maybe this is a good time to convert it to markdown as well?

mielvds · 2026-06-02T11:48:34Z

@@ -0,0 +1,40 @@
+# PyLD
+
+PyLD is a Python implementation of the [JSON-LD][] processor API.


Link is missing?

mielvds · 2026-06-02T11:49:50Z

+
+PyLD aims to conform with:
+
+- [JSON-LD 1.1][json-ld-11]


If possible, I'd like to see a table that links to the skipped tests

mielvds · 2026-06-02T11:50:26Z

+- [JSON-LD 1.1][json-ld-11]
+- [JSON-LD 1.1 Processing Algorithms and API][json-ld-11-api]
+- [JSON-LD 1.1 Framing][json-ld-11-framing]
+- The JSON-LD Working Group [test suite][wg-test-suite]


Also mention the normalization algorithms?

mielvds · 2026-06-02T11:52:00Z

@@ -0,0 +1,135 @@
+# API Reference


This was generated using some tool?

mielvds · 2026-06-02T11:53:58Z

@@ -0,0 +1,57 @@
+# Document Loaders


Add a similar document on ContextResolver? (see README)

anatoly-scherbakov added 18 commits June 1, 2026 22:42

Add MkDocs Material configuration

c3a97de

Use MkDocs Material for documentation dependencies

5594559

Add documentation homepage

8908ed4

Add installation documentation

1b4491f

Add JSON-LD quick examples documentation

c3e84e6

Add document loader overview documentation

01c3f5f

Document RequestsDocumentLoader usage

813b482

Document AioHttpDocumentLoader usage

3f3348a

Document FrozenDocumentLoader usage

570840b

Add manual public API reference

d27ad22

Add documentation deployment workflow

01e2c44

Add MkDocs serve target

a966bfa

Document MkDocs contributor commands

0747f9c

Ignore MkDocs site output

daa6776

Remove Sphinx docs Makefile

51f60bd

Remove Sphinx docs configuration

d417b98

Remove Sphinx docs index

f7e5e15

Remove Sphinx Windows build script

a5b00e8

github-advanced-security AI found potential problems Jun 1, 2026

View reviewed changes

Comment thread .github/workflows/docs.yaml Fixed

Comment thread .github/workflows/docs.yaml Fixed

Comment thread .github/workflows/docs.yaml Fixed

Comment thread .github/workflows/docs.yaml Fixed

Build documentation on every branch push

a75f9a8

Pin documentation workflow actions

af6c2e9

anatoly-scherbakov requested review from BigBlueHat and mielvds June 1, 2026 18:58

anatoly-scherbakov added 6 commits June 1, 2026 23:06

Add documentation macros module

178bb76

Add MkDocs macros dependency

747e7d2

Enable MkDocs macros plugin

fc68f8c

Render bundled contexts in frozen loader docs

d49ca6d

Import bundled contexts in docs macro

8d5417f

Install runtime dependencies for docs macros

d9d6035

mielvds requested changes Jun 2, 2026

View reviewed changes

mielvds added this to the v3.1.0 (JSON-LD 1.1: compact, flatten, frame) milestone Jun 5, 2026

		@@ -0,0 +1,40 @@
		# PyLD

		PyLD is a Python implementation of the [JSON-LD][] processor API.

Conversation

anatoly-scherbakov commented Jun 1, 2026 • edited by mielvds Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mielvds left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

anatoly-scherbakov commented Jun 1, 2026 •

edited by mielvds

Loading

github-actions Bot commented Jun 1, 2026 •

edited

Loading