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 <https://github.com/RDFLib/rdflib/issues/2272>.

6 files changed, 57 insertions, 59 deletions

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 274b3ad6..07bdc9db 100644
--- a/.readthedocs.yaml
+++ b/.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
diff --git a/devtools/requirements-rtd.txt b/devtools/requirements-rtd.txt
deleted file mode 100644
index 32af55fb..00000000
--- a/devtools/requirements-rtd.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-# This file contains requirements that get patched into readthedocs so that we
-# can build with a more up to date Sphinx than is in `poetry.lock`. This file
-# should be eliminated once we can get a more up-to-date version of sphinx in
-# poetry.lock. It is kept here so that dependabot can update it.
-Sphinx==5.3.0
diff --git a/docs/conf.py b/docs/conf.py
index 222d9b23..785c6fc6 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -322,5 +322,9 @@ if sys.version_info < (3, 9):
             ("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")])
diff --git a/poetry.lock b/poetry.lock
index 1f13f865..14eabafe 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -302,14 +302,14 @@ toml = ["tomli"]
 
 [[package]]
 name = "docutils"
-version = "0.17.1"
+version = "0.19"
 description = "Docutils -- Python Documentation Utilities"
 category = "dev"
 optional = false
-python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
+python-versions = ">=3.7"
 files = [
-    {file = "docutils-0.17.1-py2.py3-none-any.whl", hash = "sha256:cf316c8370a737a022b72b56874f6602acf974a37a9fba42ec2876387549fc61"},
-    {file = "docutils-0.17.1.tar.gz", hash = "sha256:686577d2e4c32380bb50cbb22f575ed742d58168cee37e99117a854bcd88f125"},
+    {file = "docutils-0.19-py3-none-any.whl", hash = "sha256:5e1de4d849fee02c63b040a4a3fd567f4ab104defd8a5511fbbc24a8a017efbc"},
+    {file = "docutils-0.19.tar.gz", hash = "sha256:33995a6753c30b7f577febfc2c50411fec6aac7f7ffeb7c4cfe5991072dcf9e6"},
 ]
 
 [[package]]
@@ -352,7 +352,6 @@ files = [
 ]
 
 [package.dependencies]
-importlib-metadata = {version = "<4.3", markers = "python_version < \"3.8\""}
 mccabe = ">=0.6.0,<0.7.0"
 pycodestyle = ">=2.8.0,<2.9.0"
 pyflakes = ">=2.4.0,<2.5.0"
@@ -373,7 +372,6 @@ files = [
 colorama = "*"
 entrypoints = "*"
 flake8 = ">=4.0.1,<5.0.0"
-importlib-metadata = {version = ">=1.0", markers = "python_version < \"3.8\""}
 pygments = "*"
 toml = "*"
 urllib3 = "*"
@@ -429,14 +427,14 @@ files = [
 
 [[package]]
 name = "importlib-metadata"
-version = "4.2.0"
+version = "4.13.0"
 description = "Read metadata from Python packages"
 category = "main"
 optional = false
-python-versions = ">=3.6"
+python-versions = ">=3.7"
 files = [
-    {file = "importlib_metadata-4.2.0-py3-none-any.whl", hash = "sha256:057e92c15bc8d9e8109738a48db0ccb31b4d9d5cfbee5a8670879a30be66304b"},
-    {file = "importlib_metadata-4.2.0.tar.gz", hash = "sha256:b7e52a1f8dec14a75ea73e0891f3060099ca1d8e6a462a4dff11c3e119ea1b31"},
+    {file = "importlib_metadata-4.13.0-py3-none-any.whl", hash = "sha256:8a8a81bcf996e74fee46f0d16bd3eaa382a7eb20fd82445c3ad11f4090334116"},
+    {file = "importlib_metadata-4.13.0.tar.gz", hash = "sha256:dd0173e8f150d6815e098fd354f6414b0f079af4644ddfe90c71e2fc6174346d"},
 ]
 
 [package.dependencies]
@@ -444,8 +442,9 @@ typing-extensions = {version = ">=3.6.4", markers = "python_version < \"3.8\""}
 zipp = ">=0.5"
 
 [package.extras]
-docs = ["jaraco.packaging (>=8.2)", "rst.linker (>=1.9)", "sphinx"]
-testing = ["flufl.flake8", "importlib-resources (>=1.3)", "packaging", "pep517", "pyfakefs", "pytest (>=4.6)", "pytest-black (>=0.3.7)", "pytest-checkdocs (>=2.4)", "pytest-cov", "pytest-enabler (>=1.0.1)", "pytest-flake8", "pytest-mypy"]
+docs = ["furo", "jaraco.packaging (>=9)", "jaraco.tidelift (>=1.4)", "rst.linker (>=1.9)", "sphinx (>=3.5)"]
+perf = ["ipython"]
+testing = ["flake8 (<5)", "flufl.flake8", "importlib-resources (>=1.3)", "packaging", "pyfakefs", "pytest (>=6)", "pytest-black (>=0.3.7)", "pytest-checkdocs (>=2.4)", "pytest-cov", "pytest-enabler (>=1.3)", "pytest-flake8", "pytest-mypy (>=0.9.1)", "pytest-perf (>=0.9.2)"]
 
 [[package]]
 name = "iniconfig"
@@ -810,30 +809,31 @@ files = [
 
 [[package]]
 name = "myst-parser"
-version = "0.18.1"
-description = "An extended commonmark compliant parser, with bridges to docutils & sphinx."
+version = "1.0.0"
+description = "An extended [CommonMark](https://spec.commonmark.org/) compliant parser,"
 category = "dev"
 optional = false
 python-versions = ">=3.7"
 files = [
-    {file = "myst-parser-0.18.1.tar.gz", hash = "sha256:79317f4bb2c13053dd6e64f9da1ba1da6cd9c40c8a430c447a7b146a594c246d"},
-    {file = "myst_parser-0.18.1-py3-none-any.whl", hash = "sha256:61b275b85d9f58aa327f370913ae1bec26ebad372cc99f3ab85c8ec3ee8d9fb8"},
+    {file = "myst-parser-1.0.0.tar.gz", hash = "sha256:502845659313099542bd38a2ae62f01360e7dd4b1310f025dd014dfc0439cdae"},
+    {file = "myst_parser-1.0.0-py3-none-any.whl", hash = "sha256:69fb40a586c6fa68995e6521ac0a525793935db7e724ca9bac1d33be51be9a4c"},
 ]
 
 [package.dependencies]
 docutils = ">=0.15,<0.20"
 jinja2 = "*"
 markdown-it-py = ">=1.0.0,<3.0.0"
-mdit-py-plugins = ">=0.3.1,<0.4.0"
+mdit-py-plugins = ">=0.3.4,<0.4.0"
 pyyaml = "*"
-sphinx = ">=4,<6"
-typing-extensions = "*"
+sphinx = ">=5,<7"
+typing-extensions = {version = "*", markers = "python_version < \"3.8\""}
 
 [package.extras]
-code-style = ["pre-commit (>=2.12,<3.0)"]
+code-style = ["pre-commit (>=3.0,<4.0)"]
 linkify = ["linkify-it-py (>=1.0,<2.0)"]
-rtd = ["ipython", "sphinx-book-theme", "sphinx-design", "sphinxcontrib.mermaid (>=0.7.1,<0.8.0)", "sphinxext-opengraph (>=0.6.3,<0.7.0)", "sphinxext-rediraffe (>=0.2.7,<0.3.0)"]
-testing = ["beautifulsoup4", "coverage[toml]", "pytest (>=6,<7)", "pytest-cov", "pytest-param-files (>=0.3.4,<0.4.0)", "pytest-regressions", "sphinx (<5.2)", "sphinx-pytest"]
+rtd = ["ipython", "pydata-sphinx-theme (==v0.13.0rc4)", "sphinx-autodoc2 (>=0.4.2,<0.5.0)", "sphinx-book-theme (==1.0.0rc2)", "sphinx-copybutton", "sphinx-design2", "sphinx-pyscript", "sphinx-tippy (>=0.3.1)", "sphinx-togglebutton", "sphinxext-opengraph (>=0.7.5,<0.8.0)", "sphinxext-rediraffe (>=0.2.7,<0.3.0)"]
+testing = ["beautifulsoup4", "coverage[toml]", "pytest (>=7,<8)", "pytest-cov", "pytest-param-files (>=0.3.4,<0.4.0)", "pytest-regressions", "sphinx-pytest"]
+testing-docutils = ["pygments", "pytest (>=7,<8)", "pytest-param-files (>=0.3.4,<0.4.0)"]
 
 [[package]]
 name = "networkx"
@@ -1168,28 +1168,28 @@ files = [
 
 [[package]]
 name = "sphinx"
-version = "4.3.2"
+version = "5.3.0"
 description = "Python documentation generator"
 category = "dev"
 optional = false
 python-versions = ">=3.6"
 files = [
-    {file = "Sphinx-4.3.2-py3-none-any.whl", hash = "sha256:6a11ea5dd0bdb197f9c2abc2e0ce73e01340464feaece525e64036546d24c851"},
-    {file = "Sphinx-4.3.2.tar.gz", hash = "sha256:0a8836751a68306b3fe97ecbe44db786f8479c3bf4b80e3a7f5c838657b4698c"},
+    {file = "Sphinx-5.3.0.tar.gz", hash = "sha256:51026de0a9ff9fc13c05d74913ad66047e104f56a129ff73e174eb5c3ee794b5"},
+    {file = "sphinx-5.3.0-py3-none-any.whl", hash = "sha256:060ca5c9f7ba57a08a1219e547b269fadf125ae25b06b9fa7f66768efb652d6d"},
 ]
 
 [package.dependencies]
 alabaster = ">=0.7,<0.8"
-babel = ">=1.3"
-colorama = {version = ">=0.3.5", markers = "sys_platform == \"win32\""}
-docutils = ">=0.14,<0.18"
-imagesize = "*"
-Jinja2 = ">=2.3"
-packaging = "*"
-Pygments = ">=2.0"
+babel = ">=2.9"
+colorama = {version = ">=0.4.5", markers = "sys_platform == \"win32\""}
+docutils = ">=0.14,<0.20"
+imagesize = ">=1.3"
+importlib-metadata = {version = ">=4.8", markers = "python_version < \"3.10\""}
+Jinja2 = ">=3.0"
+packaging = ">=21.0"
+Pygments = ">=2.12"
 requests = ">=2.5.0"
-setuptools = "*"
-snowballstemmer = ">=1.1"
+snowballstemmer = ">=2.0"
 sphinxcontrib-applehelp = "*"
 sphinxcontrib-devhelp = "*"
 sphinxcontrib-htmlhelp = ">=2.0.0"
@@ -1199,27 +1199,28 @@ sphinxcontrib-serializinghtml = ">=1.1.5"
 
 [package.extras]
 docs = ["sphinxcontrib-websupport"]
-lint = ["docutils-stubs", "flake8 (>=3.5.0)", "isort", "mypy (>=0.920)", "types-pkg-resources", "types-requests", "types-typed-ast"]
-test = ["cython", "html5lib", "pytest", "pytest-cov", "typed-ast"]
+lint = ["docutils-stubs", "flake8 (>=3.5.0)", "flake8-bugbear", "flake8-comprehensions", "flake8-simplify", "isort", "mypy (>=0.981)", "sphinx-lint", "types-requests", "types-typed-ast"]
+test = ["cython", "html5lib", "pytest (>=4.6)", "typed_ast"]
 
 [[package]]
 name = "sphinx-autodoc-typehints"
-version = "1.17.1"
+version = "1.22"
 description = "Type hints (PEP 484) support for the Sphinx autodoc extension"
 category = "dev"
 optional = false
 python-versions = ">=3.7"
 files = [
-    {file = "sphinx_autodoc_typehints-1.17.1-py3-none-any.whl", hash = "sha256:f16491cad05a13f4825ecdf9ee4ff02925d9a3b1cf103d4d02f2f81802cce653"},
-    {file = "sphinx_autodoc_typehints-1.17.1.tar.gz", hash = "sha256:844d7237d3f6280b0416f5375d9556cfd84df1945356fcc34b82e8aaacab40f3"},
+    {file = "sphinx_autodoc_typehints-1.22-py3-none-any.whl", hash = "sha256:ef4a8b9d52de66065aa7d3adfabf5a436feb8a2eff07c2ddc31625d8807f2b69"},
+    {file = "sphinx_autodoc_typehints-1.22.tar.gz", hash = "sha256:71fca2d5eee9b034204e4c686ab20b4d8f5eb9409396216bcae6c87c38e18ea6"},
 ]
 
 [package.dependencies]
-Sphinx = ">=4"
+sphinx = ">=5.3"
 
 [package.extras]
-testing = ["covdefaults (>=2)", "coverage (>=6)", "diff-cover (>=6.4)", "nptyping (>=1,<2)", "pytest (>=6)", "pytest-cov (>=3)", "sphobjinv (>=2)", "typing-extensions (>=3.5)"]
-type-comments = ["typed-ast (>=1.4.0)"]
+docs = ["furo (>=2022.12.7)", "sphinx (>=6.1.3)", "sphinx-autodoc-typehints (>=1.21)"]
+testing = ["covdefaults (>=2.2.2)", "coverage (>=7.0.5)", "diff-cover (>=7.3)", "nptyping (>=2.4.1)", "pytest (>=7.2.1)", "pytest-cov (>=4)", "sphobjinv (>=2.3.1)", "typing-extensions (>=4.4)"]
+type-comment = ["typed-ast (>=1.5.4)"]
 
 [[package]]
 name = "sphinxcontrib-apidoc"
@@ -1468,4 +1469,4 @@ networkx = ["networkx"]
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.7"
-content-hash = "3a6eb023f5a417d8825791a1acfb03462bc3754c611ca43fe81c7eb62c4f4752"
+content-hash = "d58fda334d4ffe3e0d4ad1752ff57134f99436d2f66839358ecdd0912a36ea73"
diff --git a/pyproject.toml b/pyproject.toml
index 2b3577a7..cbf77aeb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -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"]
diff --git a/tox.ini b/tox.ini
index a5b058cb..d2207cc6 100644
--- a/tox.ini
+++ b/tox.ini
@@ -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