Add tutorials on common cases with more examples.

Author: mielvds

docs/.pages

@@ -4,6 +4,8 @@ nav:
       - whats-new-version-4.md
       - installation.md
       - conformance.md
+  - Tutorials:
+      - tutorials
   - Reference:
       - reference
   - Project:

docs/examples/inject_context.py

@@ -0,0 +1,16 @@
+import json
+
+from pyld import jsonld
+
+doc = {
+    "name": "Ada Lovelace",
+    "homepage": "https://example.com/ada",
+}
+context = {
+    "name": "http://schema.org/name",
+    "homepage": {"@id": "http://schema.org/url", "@type": "@id"},
+}
+
+expanded = jsonld.expand(doc, {"expandContext": context})
+
+print(json.dumps(expanded, indent=2))

docs/examples/inject_context_compact.py

@@ -0,0 +1,24 @@
+import json
+
+from pyld import jsonld
+
+doc = {
+    "name": "Ada Lovelace",
+    "homepage": "https://example.com/ada",
+}
+source_context = {
+    "name": "http://schema.org/name",
+    "homepage": {"@id": "http://schema.org/url", "@type": "@id"},
+}
+output_context = {
+    "name": "http://schema.org/name",
+    "url": {"@id": "http://schema.org/url", "@type": "@id"},
+}
+
+compacted = jsonld.compact(
+    doc,
+    output_context,
+    {"expandContext": source_context},
+)
+
+print(json.dumps(compacted, indent=2))

docs/examples/open_jsonld_file.py

@@ -0,0 +1,11 @@
+import json
+from pathlib import Path
+
+from pyld import jsonld
+
+path = Path(__file__).resolve().parent / "data" / "person.jsonld"
+doc = json.loads(path.read_text())
+
+expanded = jsonld.expand(doc)
+
+print(json.dumps(expanded, indent=2))

docs/examples/open_jsonld_file_to_rdf.py

@@ -0,0 +1,11 @@
+import json
+from pathlib import Path
+
+from pyld import jsonld
+
+path = Path(__file__).resolve().parent / "data" / "person.jsonld"
+doc = json.loads(path.read_text())
+
+nquads = jsonld.to_rdf(doc, {"format": "application/n-quads"})
+
+print(nquads)

docs/examples/rdflib_parse.py

@@ -0,0 +1,16 @@
+import json
+
+from rdflib import Dataset
+
+from pyld import jsonld
+
+nquads = (
+    '<http://dbpedia.org/resource/Earth> '
+    '<http://schema.org/name> "Earth" .\n'
+)
+dataset = Dataset().parse(data=nquads, format="nquads")
+
+doc = jsonld.from_rdf(dataset)
+compacted = jsonld.compact(doc, {"name": "http://schema.org/name"})
+
+print(json.dumps(compacted, indent=2))

docs/examples/rdflib_processing.py

@@ -0,0 +1,28 @@
+import json
+
+from rdflib import Namespace, URIRef
+
+from pyld import jsonld
+
+SCHEMA = Namespace("http://schema.org/")
+subject = URIRef("http://dbpedia.org/resource/Earth")
+
+doc = {
+    "@context": {"name": str(SCHEMA.name)},
+    "@id": str(subject),
+    "name": "Earth",
+}
+
+dataset = jsonld.to_rdf(doc)
+dataset.add((subject, SCHEMA.url, URIRef("https://example.com/earth")))
+
+jsonld_doc = jsonld.from_rdf(dataset)
+compacted = jsonld.compact(
+    jsonld_doc,
+    {
+        "name": str(SCHEMA.name),
+        "homepage": {"@id": str(SCHEMA.url), "@type": "@id"},
+    },
+)
+
+print(json.dumps(compacted, indent=2))

docs/examples/rdflib_query.py

@@ -0,0 +1,19 @@
+import json
+
+from rdflib import Namespace, URIRef
+
+from pyld import jsonld
+
+SCHEMA = Namespace("http://schema.org/")
+subject = URIRef("http://dbpedia.org/resource/Earth")
+
+doc = {
+    "@context": {"name": str(SCHEMA.name)},
+    "@id": str(subject),
+    "name": "Earth",
+}
+
+dataset = jsonld.to_rdf(doc)
+names = [str(value) for value in dataset.objects(subject, SCHEMA.name)]
+
+print(json.dumps(names, indent=2))

docs/tutorials/index.md

@@ -0,0 +1,30 @@
+---
+hide: [toc]
+---
+
+# :material-school-outline: Tutorials
+
+<div class="grid cards" markdown>
+
+-   [:material-library:{ .lg .middle } RDFLib and `jsonld`](rdflib-processing.md)
+
+    ---
+
+    Convert JSON-LD to an `rdflib.Dataset`, process it with RDFLib, and convert
+    it back to JSON-LD.
+
+-   [:material-code-json:{ .lg .middle } Inject a JSON-LD `@context`](inject-context.md)
+
+    ---
+
+    Apply a context to plain JSON when the source cannot provide an in-band
+    `@context` or HTTP `Link` header.
+
+-   [:material-file-code-outline:{ .lg .middle } Open a JSON-LD file](open-jsonld-file.md)
+
+    ---
+
+    Load a local `.jsonld` file, process it with PyLD, and choose the right
+    dependencies for local or remote contexts.
+
+</div>

docs/tutorials/inject-context.md

@@ -0,0 +1,26 @@
+# :material-code-json: Inject a JSON-LD `@context`
+
+JSON-LD property names only become RDF terms when a context maps them to IRIs.
+If the input JSON has no `@context`, and the source cannot provide one through
+an HTTP `Link` header, pass the context with `expandContext`.
+
+Use this for JSON already loaded from a file, queue, database, or API client:
+
+1. Load or receive the plain JSON document.
+2. Define the context your application wants to apply.
+3. Pass that context in the operation `options` as `expandContext`.
+4. Run `jsonld.expand()` or another API that expands internally.
+
+PyLD processes `expandContext` before expansion. If the document also has its
+own `@context`, that document context is processed later and can refine or
+override term definitions for the document body.
+
+{{ example('inject_context.py', 'json') }}
+
+The same option works with APIs that expand internally, including
+`jsonld.compact()`, `jsonld.flatten()`, and `jsonld.frame()`:
+
+{{ example('inject_context_compact.py', 'json') }}
+
+Use an in-document `@context` when you control the JSON. Use `expandContext`
+when the context is application policy or transport metadata.