From 82eab189f4ae4a67201197cdd10c3a95cb2d9cce Mon Sep 17 00:00:00 2001
From: Mathias Ertl <mati@er.tl>
Date: Wed, 27 Dec 2023 18:54:54 +0100
Subject: [PATCH] update doc requirements

---
 docs/source/conf.py                      | 30 +++++++++++++++++-------
 requirements/requirements-dev-common.txt |  2 +-
 requirements/requirements-docs.txt       |  7 ++----
 3 files changed, 24 insertions(+), 15 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 5be4331ad..1e4e9657c 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -460,23 +460,31 @@
 }
 
 qualname_overrides = {
-    "KeyUsages": "django_ca.typehints.KeyUsages",
-    "OtherNames": "django_ca.typehints.OtherNames",
     "mappingproxy": "python:types.MappingProxyType",
     "MappingProxyType": "python:types.MappingProxyType",
     "cryptography.hazmat.bindings._rust.ObjectIdentifier": "cg:cryptography.x509.ObjectIdentifier",
     "cryptography.x509.extensions.ExtendedKeyUsage": "cg:cryptography.x509.ExtendedKeyUsage",
-    "x509.GeneralName": "cg:cryptography.x509.GeneralName",
+    # x509.GeneralName fixes a build error with the typehints in constants.GENERAL_NAME_TYPES. The error seems
+    # to disappear once the typehint is unquoted, which is possible with Python 3.9. It's likely that this
+    # override can be removed once support for Python 3.8 is dropped.
+    "x509.GeneralName": "cg:cryptography.x509.GeneralName",  # pragma: only py<3.9
+    # Django documents HttpRequest and HttpResponse under re-exported path names:
+    "django.http.request.HttpRequest": "django:django.http.HttpRequest",
+    "django.http.response.HttpResponse": "django:django.http.HttpResponse",
 }
 
 # Ignore (not so important) classes where the documented name does not match the documented name.
 nitpick_ignore = [
-    # Django documents these under non-canonical path names
-    ("py:class", "django.http.request.HttpRequest"),
-    ("py:class", "django.http.response.HttpResponse"),
-    ("py:class", "django_ca.typehints.OtherNames"),
-    ("py:class", "django_ca.typehints.ExtensionTypeTypeVar"),
-    ("py:class", "django_ca.typehints.KeyUsages"),
+    # When literals are used in typehints, Sphinx does not find the reference to the literal and errors with:
+    #
+    #   docstring of django_ca.constants....:1:py:class reference target not found: <name-of-literal>
+    #
+    # Note that the above message does *not* contain the full class path, just the variable name and also
+    # claims a type of "class", when "attr" would be correct. The full path can be "fixed" with
+    # `qualname_overrides` above, but that does not fix the error. Setting "reftype" to "attr" in
+    # `resolve_canonical_names()` below also works, but you still get the same error.
+    ("py:class", "OtherNames"),
+    ("py:class", "KeyUsages"),
     # asn1crypto is really used only for OtherNames, so we do not link it
     ("py:class", "asn1crypto.core.Primitive"),
     # Pydantic root model signature does not currently work
@@ -512,6 +520,10 @@ def resolve_canonical_names(app: Sphinx, doctree: document) -> None:
         alias = node.get("reftarget", None)
 
         if alias is not None and alias in qualname_overrides:
+            # This does set the type to attr in the error message, but does not fix the build error with
+            # typehints described in nitpick_ignore either:
+            # if alias == "KeyUsages":
+            #     node["reftype"] = "attr"
             node["reftarget"] = qualname_overrides[alias]
 
 
diff --git a/requirements/requirements-dev-common.txt b/requirements/requirements-dev-common.txt
index 6e8313ae1..5b80ff092 100644
--- a/requirements/requirements-dev-common.txt
+++ b/requirements/requirements-dev-common.txt
@@ -3,7 +3,7 @@ GitPython==3.1.40
 Jinja2==3.1.2
 PyYAML==6.0.1
 # Sphinx 7 requires Python>3.8, but we still support Python 3.8.
-Sphinx<7
+Sphinx==7.2.6
 coverage[toml]==7.3.4
 selenium==4.16.0
 semantic-version==2.10.0
diff --git a/requirements/requirements-docs.txt b/requirements/requirements-docs.txt
index a84ffb954..c0f0917a9 100644
--- a/requirements/requirements-docs.txt
+++ b/requirements/requirements-docs.txt
@@ -1,14 +1,11 @@
 -r requirements-dev-common.txt
-# doc8==1.0.0 and later requires docutils>19, but sphinx-rtd-theme==1.3.0
-# requires docutils<19, changes in doc8 are minimal:
-#   https://github.com/readthedocs/sphinx_rtd_theme/issues/1323
-doc8==0.11.2
+doc8==1.1.1
 numpydoc==1.6.0
 # django-ninja==0.22.2 requires pydantic<2, but rstcheck requires pydantic>=2
 # Enable once django-ninja~=1.0 is out
 #rstcheck==6.2.0
 sphinx-inline-tabs==2023.4.21
 sphinx-jinja==2.0.2
-sphinx_rtd_theme==1.3.0
+sphinx-rtd-theme==2.0.0
 sphinxcontrib-openapi==0.8.3
 sphinxcontrib-spelling==8.0.0