build: upgrade sphinx and change flake8 and related to only install on python >=3.8 (#2288)

The main aim of this change is to get to a newer version of Sphinx.

However, if just Sphinx is upgraded, poetry can't do version solving because of
the version of `importlib-metadata` that flake8 needs:

```console
$ poetry install
Updating dependencies
Resolving dependencies... (0.6s)

Because no versions of flakeheaven match >3.2.1,<4.0.0
 and flakeheaven (3.2.1) depends on flake8 (>=4.0.1,<5.0.0), flakeheaven (>=3.2.1,<4.0.0) requires flake8 (>=4.0.1,<5.0.0).
And because no versions of flake8 match >4.0.1,<5.0.0
 and flake8 (4.0.1) depends on importlib-metadata (<4.3), flakeheaven (>=3.2.1,<4.0.0) requires importlib-metadata (<4.3).
And because sphinx (5.3.0) depends on importlib-metadata (>=4.8)
 and no versions of sphinx match >5.3.0,<6.0.0, flakeheaven (>=3.2.1,<4.0.0) is incompatible with sphinx (>=5.3.0,<6.0.0).
So, because rdflib depends on both sphinx (^5.3.0) and flakeheaven (^3.2.1), version solving failed.
```

To make things work, flake8 and related is only installed for Python >=3.8,
where the built-in `importlib.metadata` is used instead of the
`importlib-metadata` package.

This means no more flake8 on python 3.7, but it is a reasonable trade-off to get
to a newer version of Sphinx, and Python 3.7 support will be dropped by
2023-06-27 anyway.

Other changes:
- Changed Read the Docs to use the Sphinx version from poetry instead of the
  custom version that was in `devtools/requirements-rtd.txt`.
- Added `typing-extensions` to the poetry `docs` dependency group as it is
  needed for docs to build correctly.
- Changed the tox `docs` environment to be closer to the Read the Docs
  environment.

Closes <#2272>.

Author: aucampia

.readthedocs.yaml

@@ -24,11 +24,6 @@ build:
     - poetry config virtualenvs.create false
     - poetry install --only=main --only=docs --extras=html
     - poetry env info
-    # This will patch Sphinx to a later version than is in poetry.lock so that
-    # we build with a more up to date Sphinx. This should be eliminated when
-    # possible in favor of having a more up to date Sphinx in poetry.lock.
-    - pip install -r devtools/requirements-rtd.txt
-
 
 sphinx:
   fail_on_warning: true

devtools/requirements-rtd.txt

@@ -322,5 +322,9 @@ def find_version(filename):
             ("py:class", "_TripleType"),
             ("py:class", "_TripleOrTriplePathType"),
             ("py:class", "TextIO"),
+            ("py:class", "Message"),
         ]
     )
+
+if sys.version_info < (3, 8):
+    nitpick_ignore.extend([("py:class", "importlib_metadata.EntryPoint")])

docs/conf.py

@@ -62,15 +62,16 @@ types-setuptools = ">=65.6.0.3,<68.0.0.0"
 setuptools = ">=65.6.3,<68.0.0"
 
 [tool.poetry.group.docs.dependencies]
-sphinx = ">4.0.0"
-myst-parser = "^0.18.0"
+sphinx = "^5.3.0"
+myst-parser = "^1.0.0"
 sphinxcontrib-apidoc = "^0.3.0"
 sphinx-autodoc-typehints = "^1.17.1"
+typing-extensions = "^4.5.0"
 
 [tool.poetry.group.flake8.dependencies]
-flake8 = ">=4.0.1" # flakeheaven is incompatible with flake8 >=5.0 (https://github.com/flakeheaven/flakeheaven/issues/132)
-flakeheaven = "^3.2.1"
-pep8-naming = "^0.13.2"
+flake8 = {version = ">=4.0.1", python = ">=3.8"} # flakeheaven is incompatible with flake8 >=5.0 (https://github.com/flakeheaven/flakeheaven/issues/132)
+flakeheaven = {version = "^3.2.1", python = ">=3.8"}
+pep8-naming = {version = "^0.13.2", python = ">=3.8"}
 
 [tool.poetry.extras]
 berkeleydb = ["berkeleydb"]

poetry.lock

@@ -54,7 +54,9 @@ passenv =
 setenv =
     PYTHONHASHSEED = 0
 commands_pre =
-    poetry install --no-root --only=docs
+    poetry lock --check
+    poetry install --only=main --only=docs --extras=html
+    poetry env info
 commands =
     poetry run sphinx-build -T -W -b html -d {envdir}/doctree docs docs/_build/html