Command-line datadoc script

docs/api_reference/dataset/datadoc.md

@@ -0,0 +1,3 @@
+# datadoc
+
+::: tripper.dataset.datadoc

docs/dataset/customisation.md

@@ -35,7 +35,9 @@ Lets assume that you already have a domain ontology with base IRI http://example
 
 First, you can add the prefix for the base IRI of your domain ontology to a custom JSON-LD context
 
-    "myonto": "http://example.com/myonto#",
+```json
+"myonto": "http://example.com/myonto#",
+```
 
 How the keywords should be specified in the context depends on whether they correspond to a data property or an object property in the ontology and whether a given datatype is expected.
 
@@ -46,15 +48,19 @@ Assume you want to add the keyword `batchNumber` to relate documented samples to
 It corresponds to the data property http://example.com/myonto#batchNumber in your domain ontology.
 By adding the following mapping to your custom JSON-LD context, `batchNumber` becomes available as a keyword for your data documentation:
 
-    "batchNumber": "myonto:batchNumber",
+```json
+"batchNumber": "myonto:batchNumber",
+```
 
 ### Literal with specific datatype
 If `batchNumber` must always be an integer, you can specify this by replacing the above mapping with the following:
 
-    "batchNumber": {
-        "@id": "myonto:batchNumber",
-        "@type": "xsd:integer"
-    },
+```json
+"batchNumber": {
+    "@id": "myonto:batchNumber",
+    "@type": "xsd:integer"
+},
+```
 
 Here "@id" refer to the IRI `batchNumber` is mapped to and "@type" its datatype. In this case we use `xsd:integer`, which is defined in the W3C `xsd` vocabulary.
 
@@ -65,11 +71,12 @@ If you want to say more about the batches, you may want to store them as individ
 In that case, you may want to add a keyword `fromBatch` which relate your sample to the batch it was taken from.
 In your ontology you may define `fromBatch` as a object property with IRI: http://example.com/myonto/fromBatch.
 
-
-    "fromBatch": {
-        "@id": "myonto:fromBatch",
-        "@type": "@id"
-    },
+```json
+"fromBatch": {
+    "@id": "myonto:fromBatch",
+    "@type": "@id"
+},
+```
 
 Here the special value "@id" for the "@type" means that the value of `fromBatch` must be an IRI.
 
@@ -80,10 +87,36 @@ Custom context can be provided for all the interfaces described in the section [
 
 ### Python dict
 Both for the single-resource and multi-resource dicts, you can add a `"@context"` key to the dict who's value is
+
 - a string containing a resolvable URL to the custom context,
 - a dict with the custom context or
 - a list of the aforementioned strings and dicts.
 
+For example
+
+```python
+{
+    "@context": [
+        # URL to a JSON file, typically a domain-specific context
+        "https://json-ld.org/contexts/person.jsonld",
+
+        # Local context
+        {
+            "fromBatch": {
+                "@id": "myonto:fromBatch",
+                "@type": "@id"
+            }
+        }
+    ],
+
+    # Documenting of the resource using keywords defined in the context
+    ...
+}
+```
+
+Note that the [default context] is always included and doesn't need to be specified explicitly.
+
+
 ### YAML file
 Since the YAML representation is just a YAML serialisation of a multi-resource dict, custom context can be provided by adding a `"@context"` keyword.
 
@@ -144,7 +177,7 @@ You can save this context to a triplestore with
 >>> ts = Triplestore("rdflib")
 >>> save_datadoc(  # doctest: +ELLIPSIS
 ...     ts,
-...      "https://raw.githubusercontent.com/EMMC-ASBL/tripper/refs/heads/dataset-docs/tests/input/custom_context.yaml",
+...      "https://raw.githubusercontent.com/EMMC-ASBL/tripper/refs/heads/master/tests/input/custom_context.yaml",
 ... )
 AttrDict(...)
 
@@ -186,8 +219,8 @@ kb:batch1 a myonto:Batch,
 
 
 ### Table
-TODO
-
+The `__init__()` method of the [TableDoc] class takes a `context` argument with witch user-defined context can be provided.
+The value of the `context` argument is the same as for the `@context` key of a [Python dict].
 
 
 User-defined resource types
@@ -201,15 +234,17 @@ Instead, the list of available resource types should be stored and retrieved fro
 
 
 
-[Documenting a resource]: ../documenting-a-resource
 [With custom context]: #with-custom-context
 [User-defined keywords]: #user-defined-keywords
-[resource types]: ../introduction#resource-types
-[predefined prefixes]: ../prefixes
-[predefined keywords]: ../keywords
-[save_dict()]: ../../api_reference/dataset/dataset/#tripper.dataset.dataset.save_dict
-[as_jsonld()]: ../../api_reference/dataset/dataset/#tripper.dataset.dataset.as_jsonld
-[save_datadoc()]:
-../../api_reference/dataset/dataset/#tripper.dataset.dataset.save_datadoc
-[TableDoc.parse_csv()]: ../../api_reference/dataset/tabledoc/#tripper.dataset.tabledoc.TableDoc.parse_csv
+[Python dict]: #python-dict
+[resource types]: introduction.md#resource-types
+[Documenting a resource]: documenting-a-resource.md
+[predefined prefixes]: prefixes.md
+[predefined keywords]: keywords.md
+[default context]: https://raw.githubusercontent.com/EMMC-ASBL/tripper/refs/heads/master/tripper/context/0.2/context.json
+[save_dict()]: ../api_reference/dataset/dataset.md#tripper.dataset.dataset.save_dict
+[as_jsonld()]: ../api_reference/dataset/dataset.md#tripper.dataset.dataset.as_jsonld
+[save_datadoc()]: ../api_reference/dataset/dataset.md#tripper.dataset.dataset.save_datadoc
+[TableDoc]: ../api_reference/dataset/tabledoc.md/#tripper.dataset.tabledoc.TableDoc
+[TableDoc.parse_csv()]: ../api_reference/dataset/tabledoc.md/#tripper.dataset.tabledoc.TableDoc.parse_csv
 [default JSON-LD context]: https://raw.githubusercontent.com/EMMC-ASBL/tripper/refs/heads/master/tripper/context/0.2/context.json

docs/dataset/documenting-a-resource.md

@@ -124,7 +124,7 @@ This dict representation accepts the following keywords:
 
 - **@context**: Optional user-defined context to be appended to the documentation of all resources.
 - **prefixes**: A dict mapping namespace prefixes to their corresponding URLs.
-- **datasets**/**distributions**/**accessServices**/**generators**/**parsers**/**resources**: A list of valid [single-resource](#single-resource-dict) dict of the given [resource type](#resource-types).
+- **datasets**/**distributions**/**accessServices**/**generators**/**parsers**/**resources**: A list of valid [single-resource](#single-resource-dict) dict of the given [resource type](introduction.md#resource-types).
 
 See [semdata.yaml] for an example of a [YAML] representation of a multi-resource dict documentation.
 
@@ -175,8 +175,7 @@ The below example shows how to save all datasets listed in the CSV file [semdata
 >>> from tripper.dataset import TableDoc
 
 >>> td = TableDoc.parse_csv(
-...     "https://raw.githubusercontent.com/EMMC-ASBL/tripper/refs/heads/tabledoc-csv/tests/input/semdata.csv",
-...     delimiter=";",
+...     "https://raw.githubusercontent.com/EMMC-ASBL/tripper/refs/heads/master/tests/input/semdata.csv",
 ...     prefixes={
 ...         "sem": "https://w3id.com/emmo/domain/sem/0.1#",
 ...         "semdata": "https://he-matchmaker.eu/data/sem/",
@@ -207,10 +206,10 @@ The below example shows how to save all datasets listed in the CSV file [semdata
 [emmo:DataSet]: https://w3id.org/emmo#EMMO_194e367c_9783_4bf5_96d0_9ad597d48d9a
 [oteio:Generator]: https://w3id.org/emmo/domain/oteio/Generator
 [oteio:Parser]: https://w3id.org/emmo/domain/oteio/Parser
-[save_dict()]: ../../api_reference/dataset/dataset/#tripper.dataset.dataset.save_dict
-[as_jsonld()]: ../../api_reference/dataset/dataset/#tripper.dataset.dataset.as_jsonld
+[save_dict()]: ../api_reference/dataset/dataset.md/#tripper.dataset.dataset.save_dict
+[as_jsonld()]: ../api_reference/dataset/dataset.md/#tripper.dataset.dataset.as_jsonld
 [save_datadoc()]:
-../../api_reference/dataset/dataset/#tripper.dataset.dataset.save_datadoc
+../api_reference/dataset/dataset.md/#tripper.dataset.dataset.save_datadoc
 [semdata.yaml]: https://raw.githubusercontent.com/EMMC-ASBL/tripper/refs/heads/master/tests/input/semdata.yaml
-[semdata.csv]: https://raw.githubusercontent.com/EMMC-ASBL/tripper/refs/heads/tabledoc-csv/tests/input/semdata.csv
+[semdata.csv]: https://raw.githubusercontent.com/EMMC-ASBL/tripper/refs/heads/master/tests/input/semdata.csv
 [TableDoc]: https://emmc-asbl.github.io/tripper/latest/api_reference/dataset/dataset/#tripper.dataset.tabledoc.TableDoc

docs/dataset/keywords.md

@@ -11,8 +11,8 @@ Here we only list those that are commonly used for data documentation with Tripp
 
 - **@context** (*IRI*): URL to or dict with user-defined JSON-LD context.
       Used to extend the keywords listed on this page with domain- or application-specific keywords.
-- **@id** (*IRI*): IRI of the documented resource.
-- **@type** (*IRI*): IRI of ontological class that the resource is an individual of.
+- **@id** (*IRI*): IRI identifying the documented resource.
+- **@type** (*IRI*): IRI of ontological class that defines what the resource *is*.
 
 
 General properties on resources used by DCAT
@@ -56,10 +56,11 @@ Other general properties on resources
 
 - **[abstract]** (*Literal*): A summary of the resource.
 - **[bibliographicCitation]** (*Literal*): A bibliographic reference for the resource. Recommended practice is to include sufficient bibliographic detail to identify the resource as unambiguously as possible.
-- **[comment]** (*Literal*): A description of the subject resource.
+- **[comment]** (*Literal*): A description of the subject resource. Use `description` instead.
 - **[deprecated]** (*Literal*): The annotation property that indicates that a given entity has been deprecated.  It should equal to `"true"^^xsd:boolean`.
 - **[isDefinedBy]** (*Literal*): Indicate a resource defining the subject resource. This property may be used to indicate an RDF vocabulary in which a resource is described.
 - **[label]** (*Literal*): Provides a human-readable version of a resource's name.
+- **[scopeNote]** (*Literal*): A note that helps to clarify the meaning and/or the use of a concept.
 - **[seeAlso]** (*Literal*): Indicates a resource that might provide additional information about the subject resource.
 - **[source]** (*Literal*): A related resource from which the described resource is derived.
 - **[statements]** (*Literal JSON*): A list of subject-predicate-object triples with additional RDF statements documenting the resource.
@@ -73,6 +74,7 @@ Properties specific for datasets
 - **[distribution]** (*IRI*): An available distribution of the dataset.
 - **[hasDatum]** (*IRI*): Relates a dataset to its datum parts. `hasDatum` relations are normally specified manually, since they are generated from the DLite data model.
 - **[inSeries]** (*IRI*): A dataset series of which the dataset is part.
+- **[isDescriptionFor]** (*IRI*): An object (e.g. a material) that this dataset describes.
 - **[isInputOf]** (*IRI*): A process that this dataset is the input to.
 - **[isOutputOf]** (*IRI*): A process that this dataset is the output of.
 - **[mappings]** (*Literal JSON*): A list of subject-predicate-object triples mapping the datamodel to ontological concepts.
@@ -124,9 +126,6 @@ Properties for parsers and generators
 - **[prefixes]**:
 -->
 
-[default JSON-LD context]: https://raw.githubusercontent.com/EMMC-ASBL/tripper/refs/heads/master/tripper/context/0.2/context.json
-[JSON-LD documentation]: https://www.w3.org/TR/json-ld/#syntax-tokens-and-keywords
-
 [accessRights]: https://www.w3.org/TR/vocab-dcat-3/#Property:resource_access_rights
 [conformsTo]: https://www.w3.org/TR/vocab-dcat-3/#Property:resource_conforms_to
 [contactPoint]: https://www.w3.org/TR/vocab-dcat-3/#Property:resource_contact_point
@@ -173,6 +172,7 @@ Properties for parsers and generators
 [distribution]: https://www.w3.org/TR/vocab-dcat-3/#Property:dataset_distribution
 [hasDatum]: https://w3id.org/emmo#EMMO_b19aacfc_5f73_4c33_9456_469c1e89a53e
 [inSeries]: https://www.w3.org/TR/vocab-dcat-3/#Property:dataset_in_series
+[isDescriptionFor]: https://w3id.org/emmo#EMMO_f702bad4_fc77_41f0_a26d_79f6444fd4f3
 [isInputOf]: https://w3id.org/emmo#EMMO_1494c1a9_00e1_40c2_a9cc_9bbf302a1cac
 [isOutputOf]: https://w3id.org/emmo#EMMO_2bb50428_568d_46e8_b8bf_59a4c5656461
 [mappings]: https://w3id.org/emmo/domain/oteio#mapping
@@ -217,11 +217,12 @@ Properties for parsers and generators
 [prefixes]:
 -->
 
-
 [DCAT]: https://www.w3.org/TR/vocab-dcat-3/
 [dcat:Dataset]: https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset
 [dcat:Distribution]: https://www.w3.org/TR/vocab-dcat-3/#Class:Distribution
 [vCard]: https://www.w3.org/TR/vcard-rdf/
 [IANA]: https://www.iana.org/assignments/media-types/media-types.xhtml
+[default JSON-LD context]: https://raw.githubusercontent.com/EMMC-ASBL/tripper/refs/heads/master/tripper/context/0.2/context.json
+[JSON-LD documentation]: https://www.w3.org/TR/json-ld/#syntax-tokens-and-keywords
 
-[User-defined keywords]: ../customisation/#user-defined-keywords
+[User-defined keywords]: customisation.md/#user-defined-keywords

docs/dataset/prefixes.md

@@ -25,4 +25,4 @@ See [User-defined prefixes] for how to extend this list with additional namespac
 
 
 [default JSON-LD context]: https://raw.githubusercontent.com/EMMC-ASBL/tripper/refs/heads/master/tripper/context/0.2/context.json
-[User-defined prefixes]: ../customisation/#user-defined-prefixes
+[User-defined prefixes]: customisation.md/#user-defined-prefixes