Update doc

docs/Readme.md

@@ -4,4 +4,3 @@ This folder contains documentation generation tools and data.
 
 Current documentation may be found in [SI_Reference_Point.md](sirp.md)
 
-Autogenerated ontology documentation (done via [Ontospy](https://github.com/lambdamusic/Ontospy) ) starts in [vocabulary_viz/index.md](vocabulary_viz/index.md).

docs/scripts/list_quantities.py

@@ -1,26 +1,16 @@
 """ Generate a list of quantities used in the SI Reference Point """
 
 import logging
+import argparse
+from pathlib import Path
 from rdflib import Graph, RDF, URIRef, BNode
-from config import TTLPATH
 
-# instantiate graph
-g = Graph()
-for ttl_file in ['quantities.ttl', 'units.ttl']:
-    file_path = TTLPATH / ttl_file
-    if not file_path:
-        logging.error("{} does not exist, did you run generate_sirp_files ?".format(file_path))
-        raise SystemExit
-    g.parse(file_path)
-
-fullURI = g.namespace_manager.expand_curie
-
-
-def unitnode_to_str(nodeID) -> str|None:
+def unitnode_to_str(g, nodeID) -> str|None:
     """ Recursively  generate unit representation strings
     Units may be compound units, i.e. nested binary trees with left and
     right terms, unit powers, multiples, etc...
     """
+    fullURI = g.namespace_manager.expand_curie
     if isinstance(nodeID, URIRef):
         """ No further processing, this is the end : fetch corresponding symbol
         and return it
@@ -43,10 +33,10 @@ def unitnode_to_str(nodeID) -> str|None:
             leftTerm = ""
             rightTerm = ""
             for s, p, o in g.triples((nodeID, fullURI("si:hasLeftUnitTerm"), None)):
-                leftTerm = unitnode_to_str(o)
+                leftTerm = unitnode_to_str(g, o)
                 break
             for s, p, o in g.triples((nodeID, fullURI("si:hasRightUnitTerm"), None)):
-                rightTerm = unitnode_to_str(o)
+                rightTerm = unitnode_to_str(g, o)
                 break
             return "{} x {}".format(leftTerm, rightTerm)
         elif nodeType == "si:UnitPower":
@@ -58,7 +48,7 @@ def unitnode_to_str(nodeID) -> str|None:
                 numericExponent = int(str(o))
                 break
             for s, p, o in g.triples((nodeID, fullURI("si:hasUnitBase"), None)):
-                unitBase = unitnode_to_str(o)
+                unitBase = unitnode_to_str(g, o)
                 break
             if numericExponent == 1:
                 return "{}".format(unitBase)
@@ -73,7 +63,7 @@ def unitnode_to_str(nodeID) -> str|None:
                 numericFactor = str(o)
                 break
             for s, p, o in g.triples((nodeID, fullURI("si:hasunitTerm"), None)):
-                unitTerm = unitnode_to_str(o)
+                unitTerm = unitnode_to_str(g, o)
                 break
             return "{} x {}".format(numericFactor, unitTerm)
         elif nodeType == "si:PrefixedUnit":
@@ -85,25 +75,44 @@ def unitnode_to_str(nodeID) -> str|None:
                 prefix = str(o)
                 break
             for s, p, o in g.triples((nodeID, fullURI("si:hasNonPrefixedUnit"), None)):
-                nonPrefixedUnit = unitnode_to_str(o)
+                nonPrefixedUnit = unitnode_to_str(g, o)
                 break
             return "{}{}".format(prefix, nonPrefixedUnit)
         else:
             logging.error("Unable to parse node {}".format(nodeID))
     return None
 
 
-is_qty = """
-SELECT DISTINCT ?qty ?unit ?prefLabelEn
-WHERE {?qty si:hasUnit ?unit .
-       ?qty skos:prefLabel ?prefLabelEn .
-       FILTER(langmatches(lang(?prefLabelEn),'en'))
-}"""
+def main():
+    parser = argparse.ArgumentParser(description="Generate list of quantities")
+    parser.add_argument(
+        "TTLPATH", type=Path,
+        help="Directory containing the TTL files")
+    args = parser.parse_args()
+    # instantiate graph
+    g = Graph()
+    for ttl_file in ['quantities.ttl', 'units.ttl']:
+        file_path = args.TTLPATH / ttl_file
+        if not file_path:
+            logging.error("{} does not exist, did you run generate_sirp_files ?".format(file_path))
+            raise SystemExit
+        g.parse(file_path)
+
+
+    is_qty = """
+    SELECT DISTINCT ?qty ?unit ?prefLabelEn
+    WHERE {?qty si:hasUnit ?unit .
+           ?qty skos:prefLabel ?prefLabelEn .
+           FILTER(langmatches(lang(?prefLabelEn),'en'))
+    }"""
+
+    qres = g.query(is_qty)
 
-qres = g.query(is_qty)
+    qty_list = []
+    for row in qres:
+        qty, unit, label = row
+        print("{0:4s} | {1:20s} | {2:}".format(
+            g.qname(qty).split(":")[1], unitnode_to_str(g, unit), label))
 
-qty_list = []
-for row in qres:
-    qty, unit, label = row
-    print("{0:4s} | {1:20s} | {2:}".format(
-        g.qname(qty).split(":")[1], unitnode_to_str(unit), label))
+if __name__ == "__main__":
+    main()

docs/scripts/make_visualizations.py

@@ -2,10 +2,11 @@
 
 import argparse
 from rdflib import Graph
-from config import TTLPATH, VOCPATH
+from si_ref_point.settings import PKG_ROOT
+from pathlib import Path
 
 
-def main(APIPATH):
+def main(APIPATH, VOCPATH=None):
     # ------------------------------------------------------------------------
     # load ttl files into knowledge graph
     g = Graph()
@@ -59,7 +60,7 @@ def main(APIPATH):
             WHERE
             {
                 ?class rdfs:subClassOf si:CompoundUnit .
-                ?prop rdfs:domain ?class . 
+                ?prop rdfs:domain ?class .
                 OPTIONAL {?prop rdfs:range ?range}
             }
             ORDER BY ?class
@@ -80,7 +81,7 @@ def main(APIPATH):
                 FILTER (?class = si:Definition || ?class = si:Constant) .
                 FILTER (?range != rdf:nil && ?domain != rdf:nil) . # filter last element of list
                 FILTER (!isBlank(?domain)) . # filter blank nodes
-                FILTER (!isBlank(?range)) . 
+                FILTER (!isBlank(?range)) .
             }
             ORDER BY ?class
             """
@@ -152,18 +153,22 @@ def main(APIPATH):
         out.write("```\n")
 
     # convert to pdfs using mermaid-cli:
-    # npx mmdc -i .\class_diagram_details.md -f -e pdf -o class_diagrams_details_converted.md
+    # npx mmdc -i ./class_diagram_details.md -f -e pdf -o class_diagrams_details_converted.md
 
     # best result with mermaid 10.9.1 (current version 11.4.2 not showing multiple self-references):
+    # 2026-05-29 : 11.15.0 still does not
     # npm install -g @mermaid-js/mermaid-cli@10.9.1
-        
+
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(
         description="Generate SI ref point vocabulary")
     parser.add_argument(
-        "--path_to_ttl",
-        default=TTLPATH,
+        "path_to_ttl", type=Path,
         help="Directory where TTLs are stored")
+    parser.add_argument(
+        "--VOCPATH", type=Path,
+        default = PKG_ROOT.parent.parent / 'docs' / 'vocabulary',
+        help="Directory for output mermaid code, default PKGROOT/docs/vocabulary")
     args = parser.parse_args()
-    main(args.path_to_ttl)
+    main(args.path_to_ttl, VOCPATH=args.VOCPATH)

docs/scripts/make_vocabulary.py

@@ -1,11 +1,12 @@
-""" Create a vocabulary file """
+""" Create a vocabulary file and the class_diagram.md file (mermaid code) """
 
 import argparse
 from rdflib import Graph, BNode, RDF
-from config import TTLPATH, VOCPATH
+from pathlib import Path
+from si_ref_point.settings import PKG_ROOT
 
 
-def main(APIPATH):
+def main(APIPATH: Path, VOCPATH: Path=None):
     # ------------------------------------------------------------------------
     # load ttl files into knowledge graph
     g = Graph()
@@ -130,6 +131,7 @@ def main(APIPATH):
 
     # Write diagram (mermaid code)
     with open(VOCPATH / 'class_diagram.md', 'w') as out:
+        out.write("```mermaid\n")
         out.write("classDiagram\n")
         for cl, vals in diagram.items():
             if vals['superclass'] != "owl:Class":
@@ -151,6 +153,7 @@ def main(APIPATH):
                 if pr['range'] and pr['range'] not in already_drawn:
                     out.write("\t`{}` --o `{}`\n".format(cl, pr['range']))
                     already_drawn.append(pr['range'])
+        out.write("```")
 
 
 def parse_multi(g, nodeID):
@@ -174,8 +177,12 @@ def parse_multi(g, nodeID):
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(description="Generate an SI Reference Point vocabulary")
-    parser.add_argument("--path_to_ttl",
-                        default=TTLPATH,
+    parser.add_argument("path_to_ttl",
+                        type=Path,
                         help="Directory where TTLs are stored")
+    parser.add_argument(
+    "--VOCPATH", type=Path,
+    default = PKG_ROOT.parent.parent / 'docs' / 'vocabulary',
+    help="Directory for output mermaid code, default PKGROOT/docs/vocabulary")
     args = parser.parse_args()
-    main(args.path_to_ttl)
+    main(args.path_to_ttl, VOCPATH=args.VOCPATH)

docs/vocabulary/class_diagram.md

@@ -1,3 +1,4 @@
+```mermaid
 classDiagram
 	`si:QuantityKind`<|--`si:CompoundQuantityKind`
 	`si:MeasurementUnit`<|--`si:CompoundUnit`
@@ -70,6 +71,7 @@ classDiagram
 	}
 	class `si:SIPrefix`{
 		+si:hasDatatype
+		+si:hasExponent
 		+si:hasScalingFactor
 	}
 	class `si:SISpecialNamedUnit`{
@@ -119,6 +121,7 @@ classDiagram
 	`si:SIDecision` --o `si:SIDecisionTarget`
 	`si:SIDecisionTarget` --o `si:SIDecision`
 	`si:SIDecisionTarget` --o `si:SIDecisionScope`
+	`si:SIPrefix` --o `xsd:short`
 	`si:SIPrefix` --o `rdfs:Literal`
 	`si:SISpecialNamedUnit` --o `xsd:boolean`
 	`si:SISpecialNamedUnit` --o `rdfs:Literal`
@@ -129,3 +132,4 @@ classDiagram
 	`si:UnitProduct` --o `si:MeasurementUnit`
 	`si:nonSIUnit` --o `xsd:boolean`
 	`si:nonSIUnit` --o `rdfs:Literal`
+```

docs/vocabulary/vocabulary.md

@@ -194,7 +194,7 @@ SI prefix
 | si:hasDatatype | si:Constant, si:SIPrefix |  |  |
 | si:hasDefiningResolution | si:Definition, si:Constant | rb:Resolution | Linking an SI definition to the resolution by which it was adopted. |
 | si:hasDefiningResolution | si:Definition, si:Constant | rb:Resolution | Linking an SI definition to the resolution by which it was adopted. |
-| si:hasNumericExponent | si:UnitPower | xsd:short |  |
+| si:hasExponent | si:SIPrefix | xsd:short |  |
 | si:hasScalingFactor | si:SIPrefix | rdfs:Literal | Linking an SI prefix to its scaling factor. |
 | si:hasSymbol |   | xsd:string | Linking a measurement unit or prefix to a symbol. |
 
@@ -210,7 +210,7 @@ SI prefix
 | si:hasDatatype | si:Constant, si:SIPrefix |  |  |
 | si:hasDefiningResolution | si:Definition, si:Constant | rb:Resolution | Linking an SI definition to the resolution by which it was adopted. |
 | si:hasDefiningResolution | si:Definition, si:Constant | rb:Resolution | Linking an SI definition to the resolution by which it was adopted. |
-| si:hasNumericExponent | si:UnitPower | xsd:short |  |
+| si:hasExponent | si:SIPrefix | xsd:short |  |
 | si:hasScalingFactor | si:SIPrefix | rdfs:Literal | Linking an SI prefix to its scaling factor. |
 | si:hasSymbol |   | xsd:string | Linking a measurement unit or prefix to a symbol. |