tidy docco after tooling extraction

Kurrawong · Dec 29, 2024 · a4ebfec · a4ebfec
1 parent 3355249
commit a4ebfec
Show file tree

Hide file tree

Showing 5 changed files with 205 additions and 84 deletions.
diff --git a/docs/assets/manifest-invalid-01.ttl b/docs/assets/manifest-invalid-01.ttl
@@ -0,0 +1,33 @@
+PREFIX mrr: <https://prez.dev/ManifestResourceRoles/>
+PREFIX prez: <https://prez.dev/>
+PREFIX prof: <http://www.w3.org/ns/dx/prof/>
+PREFIX schema: <https://schema.org/>
+
+[]
+    a prez:Manifest ;
+    prof:hasResource
+        [
+            prof:hasArtifact "catalogue.ttl" ;
+            prof:hasRole mrr:CatalogueData ;
+            schema:description "The definition of, and medata for, the container which here is a dcat:Catalog object" ;
+            schema:name "Catalogue Definition"
+        ] ,
+        [
+            prof:hasArtifact "vocabs/*.ttl" ;
+            # prof:hasRole mrr:ResourceData ;
+            schema:description "skos:ConceptsScheme objects in RDF (Turtle) files in the vocabs/ folder" ;
+            schema:name "Content Data"
+        ] ,
+        [
+            prof:hasArtifact "https://github.com/RDFLib/prez/blob/main/prez/reference_data/profiles/ogc_records_profile.ttl" ;
+            prof:hasRole mrr:CatalogueAndResourceModel ;
+            schema:description "The default Prez profile for Records API" ;
+            schema:name "Profile Definition"
+        ] ,
+        [
+            prof:hasArtifact "_background/labels.ttl" ;
+            prof:hasRole mrr:CompleteCatalogueAndResourceLabels ;
+            schema:description "An RDF file containing all the labels for the container content" ;
+            schema:name "Labels" ;
+        ] ;
+.
diff --git a/docs/assets/manifest-invalid-03.ttl b/docs/assets/manifest-invalid-03.ttl
@@ -0,0 +1,33 @@
+PREFIX mrr: <https://prez.dev/ManifestResourceRoles/>
+PREFIX prez: <https://prez.dev/>
+PREFIX prof: <http://www.w3.org/ns/dx/prof/>
+PREFIX schema: <https://schema.org/>
+
+[]
+    a prez:Manifest ;
+    prof:hasResource
+        [
+            prof:hasArtifact "catalogue.ttl" ;
+            prof:hasRole mrr:CatalogueData ;
+            schema:description "The definition of, and medata for, the container which here is a dcat:Catalog object" ;
+            schema:name "Catalogue Definition"
+        ] ,
+        [
+            prof:hasArtifact "vocabs/*.ttl" ;
+            prof:hasRole mrr:ResourceData ;
+            schema:description "skos:ConceptsScheme objects in RDF (Turtle) files in the vocabs/ folder" ;
+            schema:name "Content Data"
+        ] ,
+        [
+            prof:hasArtifact "https://github.com/RDFLib/prez/blob/main/prez/reference_data/profiles/ogc_records_profile.ttlx" ;
+            prof:hasRole mrr:CatalogueAndResourceModel ;
+            schema:description "The default Prez profile for Records API" ;
+            schema:name "Profile Definition"
+        ] ,
+        [
+            prof:hasArtifact "_background/labels.ttl" ;
+            prof:hasRole mrr:CompleteCatalogueAndResourceLabels ;
+            schema:description "An RDF file containing all the labels for the container content" ;
+            schema:name "Labels" ;
+        ] ;
+.
diff --git a/docs/assets/manifest.ttl b/docs/assets/manifest.ttl
@@ -0,0 +1,33 @@
+PREFIX mrr: <https://prez.dev/ManifestResourceRoles/>
+PREFIX prez: <https://prez.dev/>
+PREFIX prof: <http://www.w3.org/ns/dx/prof/>
+PREFIX schema: <https://schema.org/>
+
+[]
+    a prez:Manifest ;
+    prof:hasResource
+        [
+            prof:hasArtifact "catalogue.ttl" ;
+            prof:hasRole mrr:CatalogueData ;
+            schema:description "The definition of, and medata for, the container which here is a dcat:Catalog object" ;
+            schema:name "Catalogue Definition"
+        ] ,
+        [
+            prof:hasArtifact "vocabs/*.ttl" ;
+            prof:hasRole mrr:ResourceData ;
+            schema:description "skos:ConceptsScheme objects in RDF (Turtle) files in the vocabs/ folder" ;
+            schema:name "Resource Data"
+        ] ,
+        [
+            prof:hasArtifact "https://github.com/RDFLib/prez/blob/main/prez/reference_data/profiles/ogc_records_profile.ttl" ;
+            prof:hasRole mrr:CatalogueAndResourceModel ;
+            schema:description "The default Prez profile for Records API" ;
+            schema:name "Profile Definition"
+        ] ,
+        [
+            prof:hasArtifact "_background/labels.ttl" ;
+            prof:hasRole mrr:CompleteCatalogueAndResourceLabels ;
+            schema:description "An RDF file containing all the labels for the container content" ;
+            schema:name "Labels" ;
+        ] ;
+.
diff --git a/docs/assets/mrr.ttl b/docs/assets/mrr.ttl
@@ -0,0 +1,87 @@
+PREFIX cs: <https://prez.dev/ManifestResourceRoles>
+PREFIX : <https://prez.dev/ManifestResourceRoles/>
+PREFIX owl: <http://www.w3.org/2002/07/owl#>
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX schema: <https://schema.org/>
+PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
+PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+
+
+:CompleteCatalogueAndResourceLabels
+    a skos:Concept ;
+    skos:definition "All the labels - possibly indluding names, descriptions & seeAlso links - for the Catalogue and Resource objects" ;
+    skos:inScheme cs: ;
+    skos:prefLabel "Complete Catalogue and Resource Labels" ;
+.
+
+:CatalogueAndResourceModel
+    a skos:Concept ;
+    skos:definition "The default model for the container and the content. Must be a set of SAHCL Shapes" ;
+    skos:inScheme cs: ;
+    skos:prefLabel "Catalogue & Resource Model" ;
+.
+
+:CatalogueData
+    a skos:Concept ;
+    skos:definition "Data for the container, usually a Catalogue, including the identity of it and each item fo content" ;
+    skos:inScheme cs: ;
+    skos:prefLabel "Catalogue Data" ;
+.
+
+:CatalogueModel
+    a skos:Concept ;
+    skos:definition "The default model for the container. Must be a set of SAHCL Shapes" ;
+    skos:inScheme cs: ;
+    skos:prefLabel "Catalogue Model" ;
+.
+
+:ResourceData
+    a skos:Concept ;
+    skos:definition "Data for the content of the container" ;
+    skos:inScheme cs: ;
+    skos:prefLabel "Resource Data" ;
+.
+
+:ResourceModel
+    a skos:Concept ;
+    skos:definition "The default model for the content. Must be a set of SAHCL Shapes" ;
+    skos:inScheme cs: ;
+    skos:prefLabel "Resource Model" ;
+.
+
+:IncompleteCatalogueAndResourceLabels
+    a skos:Concept ;
+    skos:definition "Some of the labels - possibly including names, descriptions & seeAlso links - for the Catalogue and Resource objects" ;
+    skos:inScheme cs: ;
+    skos:prefLabel "Incomplete Catalogue and Resource Labels" ;
+.
+
+<https://kurrawong.ai>
+    a schema:Organization ;
+    schema:name "KurrawongAI" ;
+    schema:url "https://kurrawong.ai"^^xsd:anyURI ;
+.
+
+:1.0.0
+    rdfs:label "1.0.0" ;
+.
+
+cs:
+    a skos:ConceptScheme ;
+    owl:versionIRI :1.0.0 ;
+    owl:versionInfo "1.0.0: First public version" ;
+    skos:definition "This vocabulary is a test vocabulary showing the use of images within Concept definitions"@en ;
+    skos:hasTopConcept
+        :CompleteCatalogueAndResourceLabels ,
+        :CatalogueAndResourceModel ,
+        :CatalogueData ,
+        :CatalogueModel ,
+        :ResourceData ,
+        :IncompleteCatalogueAndResourceLabels ;
+    skos:historyNote "Create in 2024 for Prez data loading" ;
+    skos:prefLabel "Manifest Resource Roles Vocabulary" ;
+    schema:creator <https://kurrawong.ai> ;
+    schema:dateCreated "2024-11-29"^^xsd:date ;
+    schema:dateModified "2024-12-17"^^xsd:date ;
+    schema:publisher <https://kurrawong.ai> ;
+.
diff --git a/docs/manifest.md b/docs/manifest.md
@@ -2,13 +2,12 @@
 
 A Prez Manifest is an RDF file that describes and links to a set of resources that can be loaded into an RDF database for Prez to provide access to.
 
-To support Manifest creation and use, the following tools are provides:
+This pase defines the Prez Manifest specification and links to relevant tools.
 
 1. [The model](#model)
 2. [Manifest Resource Roles Vocabulary](#roles-vocabulary)
-3. [Validator](#validator)
-4. [Build Scripts](#build-scripts)
-5. [Examples](#examples)
+3. [Examples](#examples)
+4. [Tools](#tools)
 
 ## Model
 
@@ -30,6 +29,7 @@ Each Resource Descriptor MUST also have exactly one `prof:hasRole` predicate ind
 Each Resource Descriptor MAY have a `schema:name` and/r a `schema:description` predicate indicating literal resources naming and describing it.
 
 <a id="roles-vocabulary"></a>
+
 ## Manifest Resource Roles Vocabulary
 
 This roles vocabulary contains the allowed roles that a resource can play with respect to a Manifest.
@@ -55,103 +55,38 @@ Human-readable form:
 Machine-readable form:
 
 ```
---8<-- "manifest/mrr.ttl"
+--8<-- "docs/assets/mrr.ttl"
 ```
 
---8<-- "mrr.ttl"
-
 The IRI for automatic retrieval of this vocabulary file is: <https://prez.dev/ManifestResourceRoles>.
 
+## Examples
 
-## Validator
-
-This simple [SHACL](https://www.w3.org/TR/shacl/) validator "Shapes" file can be used by SHACL validation software to test the validity of a Manifest RDF file with respect to this model:
+**Valid**:
 
 ```
---8<-- "manifest/validator.ttl"
+--8<-- "docs/assets/manifest.ttl"
 ```
 
-The IRI for automatic retrieval of this Shapes file is: <https://prez.dev/manifest/validator>.
-
-The recommended tools to perform validation using this Shapes file are:
-
-1. [KurrawongAI's Online Validator](https://tools.dev.kurrawong.ai/validate) - this Shapes file is pre-loaded
-2. [pySHACL Python tool](https://pypi.org/project/pyshacl/) - for scripted validation
-
-## Build Scripts
-
-### Documentor
+**Invalid** - second Resource Descriptor does not indicate a role as it is commented out
 
-The `documentor.py` Python script in this documentation's repository creates a "Prez Resources" table in either Markdown or ASCIIDOC from a Manifest file which it validates first:
-
-* <https://github.com/Kurrawong/prez.dev/blob/main/manifest/documentation.py>
-
-#### Use
 ```
-usage: documentor.py [-h] [-v] [-t {markdown,asciidoc}] input
-
-positional arguments:
-  input                 File, Folder or Sparql Endpoint to read RDF from
-
-options:
-  -h, --help            show this help message and exit
-  -v, --version         show program's version number and exit
-  -t {markdown,asciidoc}, --type {markdown,asciidoc}
-                        The type of markup you want to export: Markdown or ASCCIDOC
+--8<-- "docs/assets/manifest-invalid-01.ttl"
 ```
 
-#### Example
-
-Using the first example Manifest, `example01.ttl` in this too's repository and also given in the [Example](#examples) section below:
+**Invalid** - the third resource specifies an invalid location, the non-existent web address of https://github.com/RDFLib/prez/blob/main/prez/reference_data/profiles/ogc_records_profile.ttlx which has had an extra 'x' added at the end.
 
 ```
-~$ python documentor.py example01.ttl
+--8<-- "docs/assets/manifest-invalid-03.ttl"
+--8<-- "docs/assets/manifest-invalid-03.ttl"
 ```
 
-produces:
-
-```
-Resource | Role | Description
---- | --- | ---
-Catalogue Definition, [`catalogue.ttl`](catalogue.ttl) | [Container Data](https://prez.dev/ManifestResourceRoles/ContainerData) | The definition of, and medata for, the container which here is a dcat:Catalog object
-Content, [`vocabs/*.ttl`](vocabs/*.ttl) | [Content Data](https://prez.dev/ManifestResourceRoles/ContentData) | skos:ConceptsScheme objects in RDF (Turtle) files in the vocabs/ folder
-Profile Definition, [`ogc_records_profile.ttl`](https://github.com/RDFLib/prez/blob/main/prez/reference_data/profiles/ogc_records_profile.ttl) | [Container & Content Model](https://prez.dev/ManifestResourceRoles/ContainerAndContentModel) | The default Prez profile for Records API
-Labels file, [`_background/labels.ttl`](_background/labels.ttl) | [Complete Content and Container Labels](https://prez.dev/ManifestResourceRoles/CompleteContainerAndContentLabels) | An RDF file containing all the labels for the container content
+## Tools
 
-```
+The `prez-manifest` Python package, available at https://github.com/Kurrawong/prez-manifest, provides a number of functions to to work with Prez Manifests. The functions provided are:
 
-which renders as:
+* `create_table`: creates an ASCIIDOC or Markdown table of Manifest content from a Manifest file
+* `validate`: validates that a Manifest file conforms to the specification and that all linked-to assets are available
+* `load`: loads a Manifest file, and all the content it specifies, into either an n-quads file or a Fuseki database
 
-| Resource                                                                                                                                       | Role                                                                                                              | Description                                                                          |
-|------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
-| Catalogue Definition, [`catalogue.ttl`](catalogue.ttl)                                                                                         | [Container Data](https://prez.dev/ManifestResourceRoles/ContainerData)                                            | The definition of, and medata for, the container which here is a dcat:Catalog object |
-| Content, [`vocabs/*.ttl`](vocabs/*.ttl)                                                                                                        | [Content Data](https://prez.dev/ManifestResourceRoles/ContentData)                                                | skos:ConceptsScheme objects in RDF (Turtle) files in the vocabs/ folder              |
-| Profile Definition, [`ogc_records_profile.ttl`](https://github.com/RDFLib/prez/blob/main/prez/reference_data/profiles/ogc_records_profile.ttl) | [Container & Content Model](https://prez.dev/ManifestResourceRoles/ContainerAndContentModel)                      | The default Prez profile for Records API                                             |
-| Labels file, [`_background/labels.ttl`](_background/labels.ttl)                                                                                | [Complete Content and Container Labels](https://prez.dev/ManifestResourceRoles/CompleteContainerAndContentLabels) | An RDF file containing all the labels for the container content                      |
-
-### Loader
-
-==_In Progress_==
-
-The `loader.py` Python script in this documentation's repository creates a 
-
-* <https://github.com/Kurrawong/prez.dev/blob/main/manifest/loader.py>
-
-## Examples
-
-See the simple and always up-to-date [KurrawongAI Demo Vocabularies manifest](https://github.com/Kurrawong/demo-vocabs/manifest.ttl):
-
-Full:
-```
---8<-- "manifest/example01.ttl"
-```
-
-Partial:
-```
---8<-- "manifest/example02.ttl"
-```
-
-Invalid (second Resource Descriptor does not indicate a role)
-```
---8<-- "manifest/example03.ttl"
-```
+See the package's repository for details.