Merge pull request #1682 from aucampia/iwana-20220122T0047-term_class_diagmaster

Add a class diagram for terms.

6 files changed, 89 insertions, 9 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 6c170963..e8abde75 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -37,6 +37,7 @@ extensions = [
     "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
     "myst_parser",
+    "sphinxcontrib.kroki",
 ]
 
 apidoc_module_dir = "../rdflib"
diff --git a/docs/docs.rst b/docs/docs.rst
index 5f51f645..4643e10d 100644
--- a/docs/docs.rst
+++ b/docs/docs.rst
@@ -10,22 +10,23 @@ These docs are generated with Sphinx.
 Sphinx makes it very easy to pull in doc-strings from modules,
 classes, methods, etc.  When writing doc-strings, special reST fields
 can be used to annotate parameters, return-types, etc. This makes for
-pretty API docs:
-
-http://sphinx-doc.org/domains.html?highlight=param#info-field-lists
+pretty API docs. More information about sphinx can be found `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html>`_.
 
 Building
 --------
 
-To build you must have the ``sphinx`` package installed:
+To build you must have the ``sphinx`` and some additional package installed.
+
+The documentation's full set of requirements is listed in the ``sphinx-requirements.txt`` file within the :file:`docs/` directory.
+
+To install the requirements for building documentation run:
 
 .. code-block:: bash
 
-  pip install sphinx
+  pip install -r docs/sphinx-requirements.txt
 
-See the documentation's full set of requirements in the ``sphinx-require,ens.txt`` file within the :file:`docs/` directory.
 
- Once you have all the requirements installed you can run this command in the rdflib root directory:
+Once you have all the requirements installed you can run this command in the rdflib root directory:
 
 .. code-block:: bash
 
@@ -33,6 +34,12 @@ See the documentation's full set of requirements in the ``sphinx-require,ens.txt
 
 Docs will be generated in :file:`build/sphinx/html/` and API documentation, generated from doc-strings, will be placed in :file:`docs/apidocs/`.
 
+There is also a `tox <https://tox.wiki/en/latest/>`_ environment for building documentation:
+
+.. code-block:: bash
+
+  tox -e docs
+
 API Docs
 --------
 
diff --git a/docs/rdf_terms.rst b/docs/rdf_terms.rst
index c8468407..a9682325 100644
--- a/docs/rdf_terms.rst
+++ b/docs/rdf_terms.rst
@@ -6,7 +6,71 @@ RDF terms in rdflib
 
 Terms are the kinds of objects that can appear in a quoted/asserted triples. Those that are part of core  RDF concepts are: ``Blank Node``, ``URI Reference`` and ``Literal``, the latter consisting of a literal value and either a `datatype <https://www.w3.org/TR/xmlschema-2/#built-in-datatypes>`_ or an :rfc:`3066` language tag.
 
-All terms in RDFLib are sub-classes of the :class:`rdflib.term.Identifier` class.
+All terms in RDFLib are sub-classes of the :class:`rdflib.term.Identifier` class. A class diagram of the various terms can be seen in the :ref:`term_class_hierarchy` diagram.
+
+.. _term_class_hierarchy:
+.. kroki::
+   :caption: Term Class Hierarchy
+   :type: plantuml
+
+@startuml
+skinparam shadowing false
+skinparam monochrome true
+skinparam packageStyle rectangle
+skinparam backgroundColor FFFFFE
+
+class Node
+
+class Identifier {
+    eq(other) -> bool
+    neq(other) -> bool
+    startswith(prefix: str, start, end) -> bool
+}
+Identifier -up-|> Node
+
+class IdentifiedNode {
+    toPython() -> str
+}
+IdentifiedNode -up-|> Identifier
+
+class URIRef {
+    n3(namespace_manager) -> str
+    defrag() -> URIRef
+    de_skolemize() -> BNode
+}
+URIRef -up-|> IdentifiedNode
+
+
+class Genid
+Genid -up-|> URIRef
+
+class RDFLibGenid
+RDFLibGenid -up-|> Genid
+
+class BNode {
+    n3(namespace_manager) -> str
+    skolemize(authority, basepath) -> RDFLibGenid
+}
+BNode -up-|> IdentifiedNode
+
+class Literal {
+    datatype: Optional[str]
+    lang: Optional[str]
+    value: Any
+
+    normalize() -> Literal
+    n3(namespace_manager) -> str
+    toPython() -> str
+}
+Literal -up-|> Identifier
+
+class Variable {
+    n3(namespace_manager) -> str
+    toPython() -> str
+}
+Variable -up-|> Identifier
+
+@enduml
 
 Nodes are a subset of the Terms that the underlying store actually persists.
 The set of such Terms depends on whether or not the store is formula-aware. 
diff --git a/docs/sphinx-requirements.txt b/docs/sphinx-requirements.txt
index f85e30e1..1140fd3f 100644
--- a/docs/sphinx-requirements.txt
+++ b/docs/sphinx-requirements.txt
@@ -1,3 +1,5 @@
 sphinx==4.4.0
 sphinxcontrib-apidoc
 git+https://github.com/gniezen/n3pygments.git
+myst-parser
+sphinxcontrib-kroki
diff --git a/requirements.dev.txt b/requirements.dev.txt
index c2716dd4..fc814ba7 100644
--- a/requirements.dev.txt
+++ b/requirements.dev.txt
@@ -12,3 +12,4 @@ sphinx
 sphinxcontrib-apidoc
 myst-parser
 types-setuptools
+sphinxcontrib-kroki
diff --git a/setup.py b/setup.py
index 1c839eed..cd42d33e 100644
--- a/setup.py
+++ b/setup.py
@@ -23,7 +23,12 @@ kwargs["tests_require"] = [
 kwargs["extras_require"] = {
     "html": ["html5lib"],
     "tests": kwargs["tests_require"],
-    "docs": ["sphinx < 5", "sphinxcontrib-apidoc", "myst-parser"],
+    "docs": [
+        "sphinx < 5",
+        "sphinxcontrib-apidoc",
+        "myst-parser",
+        "sphinxcontrib-kroki",
+    ],
 }