diff options
-rw-r--r-- | docs/conf.py | 1 | ||||
-rw-r--r-- | docs/docs.rst | 21 | ||||
-rw-r--r-- | docs/rdf_terms.rst | 66 | ||||
-rw-r--r-- | docs/sphinx-requirements.txt | 2 | ||||
-rw-r--r-- | requirements.dev.txt | 1 | ||||
-rw-r--r-- | setup.py | 7 |
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 @@ -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", + ], } |