Add a class diagram for terms.

[aucampia]

The diagram is based on the diagram created by
Graham Higgins (@gjhiggins) in #1526

This shows the class heirarchy of various terms such as Identifier,
IdentifiedNode, URIRef, Literal, etc.

The diagram is in plantuml and
compiled to svg by the
kroki extension for sphinx.

Diagrams can be rendered from the plantuml at https://kroki.io/.

Other changes:

• Some updates to the "Writing RDFLib Documentation" page.

[aucampia]

Preview:

[aucampia]

The diagram itself can be seen in

click the image to go to an editor for it.

[nicholascar]

Thanks @aucampia, as always! I think the diagram really helps and it looks really great. I think I'll do more of these in other Python projects of mine that have interesting class hierarchies (I am actually a data modeller, not a software engineer after all).

Sadly, looking at the diagram, I think we need to tidy up the classes more:

I think we should update URIRef to a more naturally-named IRI class - while retaining an alias so people can still call URIRef in code, if that's possible - and also consider renaming Identifier to Term to avoid overuse of the word identifier, while retaining a legacy alias too. Like the potential ConjunctiveGraph / Dataset deduplication, these structures and names matter for they cloud understanding if bad and help it greatly if good.

Something for rdflib 7.0.0...

Waiting for a review from @gjhiggins since he made the first class diagram.

[ghost]

Puts my clumsy effort to shame, well worthwhile addition.

[ghost]

Documentation note - Variable is noticeably missing from the docs. The docstring is laconic:

class Variable(Identifier):
    """
    A Variable - this is used for querying, or in Formula aware
    graphs, where Variables can stored in the graph
    """

But there are examples of the former and the W3's “Notation 3” document has a section devoted to Formulae which can usefully be mined for content to flesh out a description of the latter.

[nicholascar]

I had to make a small update to get the diagram rendering: tab in all in so Sphinx, at least on my computer, could interpret it correctly. Fix in a new PR I'm about to make for the multiple namespaces issue.

[aucampia]

We should probably do some manner of publishing of the site from master so we can also spot potential issues with docs before a release.

[nicholascar]

We do already have master being built over at readthedocs into latest documentation, as opposed to the latest release being built into stable, so we should easily be able to see what the next release’ documentation will look like before a release

[edmondchuc]

Maybe build a docs preview on each PR. You can see how it works here. ternaustralia/linkeddata-site#85. And here is the GitHub Actions workflow. https://github.com/ternaustralia/linkeddata-site/blob/master/.github/workflows/preview.yml. It utilises the free surge.sh service for serving the static site content.

Alternatively, render.com also has a generous free tier with PR previews for static sites as well.

[aucampia]

Maybe build a docs preview on each PR. You can see how it works here. ternaustralia/linkeddata-site#85. And here is the GitHub Actions workflow. https://github.com/ternaustralia/linkeddata-site/blob/master/.github/workflows/preview.yml. It utilises the free surge.sh service for serving the static site content.

Alternatively, render.com also has a generous free tier with PR previews for static sites as well.

Thanks for this, I will have a look, will be very helpful to do.

[aucampia]

We do already have master being built over at readthedocs into latest documentation, as opposed to the latest release being built into stable, so we should easily be able to see what the next release’ documentation will look like before a release

I had a look at https://readthedocs.org/projects/rdflib/builds/ and it seems latests was not built recently, what triggers an update there?

[nicholascar]

what triggers an update there?

At the moment, I think it's all manual, as in someone has to go in an press 'build' for latest, stable and release builds (e.g. 5.0.0) when a new release is made.

Auto-building would be better but I don't know how to auto-build in reathedocs but I'm sure it's possible as I think many PyPI projects auto-build.

[edmondchuc]

@aucampia I just noticed RTD also provides pull request previews. See https://docs.readthedocs.io/en/stable/pull-requests.html