Run doctest on docs in docs folder

[aucampia]

We are currently not running doctest on docs in the docs folder, in part because it fails. We should fix the docs so that doctests pass for them and then enable doctest.

I had a look at this and, with the exception of a couple of recently-added python (should be pycon) codeblocks in rdf_terms.rst, there aren't any doctests to be run - all the example code is marked off as code-block which pytest ignores.

Just to check the reality, I installed Sybil and checked the state of affairs, there are about a dozen uncorrectable failures, all but one stemming from non-existent files from example code such as g.parse("foo.ttl") the exception being a parser failure to parse danbri's old livejournal FOAF file.

The handful of correctable failures are all concerned with missing imports/variable bindings that can be trivially addressed by using .. invisible-code-block: python --- if we care to make Sybil a dependency of [test]

[aucampia]

Maybe I should clarify a bit, these are the errors I'm referring to:

https://gist.github.com/aucampia/b80c0254d06b857be9250cfe319bbf8d#file-failures-txt

$ PATH=$(readlink -f .venv)/bin:${PATH} PYTHONPATH=$(readlink -f .venv) make -C docs/ doctest
...
Doctest summary
===============
  719 tests
  471 failures in tests
    0 failures in setup code
    0 failures in cleanup code
build finished with problems.
make: *** [Makefile:86: doctest] Error 1
make: Leaving directory '/home/iwana/sw/d/github.com/iafork/rdflib.clean/docs'

[aucampia]

I'm open to using Sybil also - and I'm not entirely sure about doctest, I just recall I saw it and it bothered me a bit.

[aucampia]

Okay, after taking a closer look at the failures, I see most of them are actually doctests which come in with autodoc, which is a bit unfortunate, not sure what to do about it. I think there is some misconfiguration somewhere.

[aucampia]

The right solution here may be to run .venv/bin/python3 -m pytest --doctest-glob='*.rst' docs/, or at least add --doctest-glob='*.rst' to pytest config. I will test it some more later.

$ .venv/bin/python3 -m pytest --doctest-glob='*.rst' docs/
============================================================================ test session starts ============================================================================
platform linux -- Python 3.9.12, pytest-7.1.1, pluggy-1.0.0
rootdir: /home/iwana/sw/d/github.com/iafork/rdflib.cleanish, configfile: pyproject.toml
plugins: subtests-0.7.0, md-report-0.2.0, cov-3.0.0
collected 2 items                                                                                                                                                           

docs/namespaces_and_bindings.rst .                                                                                                                                    [ 50%]
docs/rdf_terms.rst F                                                                                                                                                  [100%]

================================================================================= FAILURES ==================================================================================
__________________________________________________________________________ [doctest] rdf_terms.rst __________________________________________________________________________
131 Here is the *BNode* class' auto-built documentation:
132 
133 .. autoclass:: rdflib.term.BNode
134     :noindex:
135 
136 .. code-block:: python
137 
138     >>> from rdflib import BNode
139     >>> bn = BNode()
140     >>> bn
Expected:
    rdflib.term.BNode('AFwALAKU0')
Got:
    rdflib.term.BNode('Na6850686814e4afa84fb1cade539db08')

/home/iwana/sw/d/github.com/iafork/rdflib.cleanish/docs/rdf_terms.rst:140: DocTestFailure
========================================================================== short test summary info ==========================================================================
FAILED docs/rdf_terms.rst::rdf_terms.rst
======================================================================== 1 failed, 1 passed in 0.23s ========================================================================

[aucampia]

even better:

$ git diff
diff --git a/docs/rdf_terms.rst b/docs/rdf_terms.rst
index 2185182c..8604dda3 100644
--- a/docs/rdf_terms.rst
+++ b/docs/rdf_terms.rst
@@ -137,9 +137,9 @@ Here is the *BNode* class' auto-built documentation:
 
     >>> from rdflib import BNode
     >>> bn = BNode()
-    >>> bn
+    >>> bn # doctest: +SKIP
     rdflib.term.BNode('AFwALAKU0')
-    >>> bn.n3()
+    >>> bn.n3() # doctest: +SKIP
     '_:AFwALAKU0'
     
     
$ .venv/bin/python3 -m pytest --doctest-glob='*.txt' --doctest-glob='*.rst' --ignore=docs/_build/ docs/
============================================================================ test session starts ============================================================================
platform linux -- Python 3.9.12, pytest-7.1.1, pluggy-1.0.0
rootdir: /home/iwana/sw/d/github.com/iafork/rdflib.cleanish, configfile: pyproject.toml
plugins: subtests-0.7.0, md-report-0.2.0, cov-3.0.0
collected 2 items                                                                                                                                                           

docs/namespaces_and_bindings.rst .                                                                                                                                    [ 50%]
docs/rdf_terms.rst .                                                                                                                                                  [100%]

============================================================================= 2 passed in 0.15s =============================================================================