Merge pull request #10 from rudof-project/update-pyrudof-api

docs: update pyrudof api, restructure book into parts and add property graph and shacl 1.2 chapters

Author: labra

.gitignore

@@ -4,7 +4,13 @@ __pycache__/
 *$py.class
 
 # Jupyter notebook build files
-_build/ 
+_build/
+
+# Diagram intermediates written by the notebooks at run time. Committing these
+# is actively harmful: a stale out.png gets displayed when the PlantUML step
+# fails, so a broken diagram looks like a working one.
+out.puml
+out.png
 
 # C extensions
 *.so

README.md

@@ -1,13 +1,40 @@
 # rudof tutorials
 
-This repository contains the source code of some [Jupiter books](https://rudof-project.github.io/tutorials/intro.html) that can be used as small tutorials of [rudof](https://rudof-project.github.io/). 
+Source for [**Shaping Knowledge Graphs**](https://rudof-project.github.io/tutorials/intro.html),
+a [Jupyter Book](https://jupyterbook.org/) that introduces RDF, SPARQL, ShEx, SHACL, DCTAP
+and property graphs through runnable examples built with
+[rudof](https://rudof-project.github.io/rudof/).
 
-Some links:
-* [Jupiter-books reference](https://jupyterbook.org/en/stable/start/overview.html)
+Each chapter is a notebook under [`rudof/`](rudof/) and can be run as you read, either
+locally or in [Google Colab](https://colab.research.google.com/) via the launch button at
+the top of each page.
 
-## 🚀 Quick Start
+## Chapters
+
+| Notebook | Topic |
+| --- | --- |
+| [`rudof.ipynb`](rudof/rudof.ipynb) | the `Rudof` session, errors, configuration, prefixes |
+| [`rdf.ipynb`](rudof/rdf.ipynb) | the RDF data model, formats, visualization, node neighbourhoods |
+| [`sparql.ipynb`](rudof/sparql.ipynb) | querying local graphs and remote endpoints |
+| [`shex.ipynb`](rudof/shex.ipynb) | shape expressions, shape maps, validation reports |
+| [`shacl.ipynb`](rudof/shacl.ipynb) | shapes as RDF, targets, validation reports |
+| [`dctap.ipynb`](rudof/dctap.ipynb) | modelling in a spreadsheet, converting to ShEx |
+| [`rdf12.ipynb`](rudof/rdf12.ipynb) | RDF 1.2 triple terms and annotations |
+| [`sparql12.ipynb`](rudof/sparql12.ipynb) | querying those annotations with SPARQL 1.2 |
+| [`compare.ipynb`](rudof/compare.ipynb) | structural comparison of two schemas |
+| [`service_description.ipynb`](rudof/service_description.ipynb) | what a SPARQL endpoint says about itself |
+| [`property_graphs.ipynb`](rudof/property_graphs.ipynb) | PG schemas, validation and Cypher |
+| [`rudof_generate.ipynb`](rudof/rudof_generate.ipynb) | generating synthetic data from a schema |
+
+## Requirements
+
+The notebooks target [`pyrudof`](https://pypi.org/project/pyrudof/) **0.3.22 or later**,
+and need Python 3.10 or newer. Several chapters reach the network: public SPARQL endpoints (Wikidata, DBpedia, UniProt) and the PlantUML server used to render diagrams.
+
+## Quick start
 
 ### 1. Clone and install
+
 ```bash
 git clone https://github.com/rudof-project/tutorials.git
 cd tutorials
@@ -20,25 +47,29 @@ pip install -r requirements.txt
 jupyter-book build rudof
 ```
 
+Every notebook is re-executed on each build (`execute_notebooks: force` in
+[`rudof/_config.yml`](rudof/_config.yml)), so a build failure means a chapter no longer runs
+against the current `pyrudof` — which is the point.
 
-### 3. Manually publish books on gh-pages 
+The result lands in `rudof/_build/html`.
 
-Note, this is no longer necessary because we publish the book through github Actions.
+### 3. Publish
 
-```bash
-ghp-import -n -p -f rudof/_build/html
-```
+Publishing happens automatically through the
+[`deploy-book` GitHub Action](.github/workflows/deploy.yml) on every push to `main` that
+touches `rudof/`.
 
 ### Cleaning build files and cache
 
-Sometimes it is necessary to clean the cache when there are new versions of the libraries. To clean the built drectory use:
+New versions of the libraries sometimes need a clean build:
 
 ```bash
-jupyter-book clean rudof
+jupyter-book clean rudof          # the build directory
+jupyter-book clean rudof --all    # also the jupyter_cache
 ```
 
-If you want to clean also the `jupyter_cache`, use:
+## Links
 
-```bash
-jupyter-book clean rudof --all
-```
+* [rudof documentation](https://rudof-project.github.io/rudof/)
+* [`pyrudof` API reference](https://pyrudof.readthedocs.io/)
+* [Jupyter Book reference](https://jupyterbook.org/en/stable/start/overview.html)

environment.yml

@@ -3,7 +3,9 @@ dependencies:
   - python=3.12
   - pip
   - pip:
-      - jupyter-book
+      - jupyter-book==1.0.4
       - ghp-import
       - jupyter
       - notebook
+      - pyrudof>=0.3.22
+      - plantuml

requirements.txt

@@ -2,3 +2,10 @@ jupyter-book==1.0.4
 ghp-import
 jupyter
 notebook
+
+# The library the tutorials are about. 0.3.22 is the first release with the
+# restructured Python bindings (result objects, RudofError hierarchy, Rudof()).
+pyrudof>=0.3.22
+
+# Used by several notebooks to render RDF graphs and schemas as diagrams.
+plantuml