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

…_diag

Add a class diagram for terms.

docs/conf.py

@@ -37,6 +37,7 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
     "myst_parser",
+    "sphinxcontrib.kroki",
 ]
 
 apidoc_module_dir = "../rdflib"

docs/docs.rst

@@ -10,29 +10,36 @@ 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
 
   python setup.py build_sphinx
 
 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
 --------
 

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. 

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

requirements.dev.txt

@@ -12,3 +12,4 @@ sphinx
 sphinxcontrib-apidoc
 myst-parser
 types-setuptools
+sphinxcontrib-kroki

setup.py

@@ -23,7 +23,12 @@
 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",
+    ],
 }