Merge pull request #58 from sphinx-doc/bugfix/readthedocs

Fix readthedocs build

Author: timobrembeck

.readthedocs.yaml

@@ -5,6 +5,12 @@
 # Required
 version: 2
 
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py

docs/conf.py

@@ -31,6 +31,9 @@
 # Warn about all references where the target cannot be found
 nitpicky = True
 
+# A list of (type, target) tuples that should be ignored when :attr:`nitpicky` is ``True``
+nitpick_ignore = [("py:class", "sphinx.ext.autodoc.Options")]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["templates"]
 

sphinxcontrib_django/__init__.py

@@ -6,12 +6,15 @@
 
 __version__ = "2.5"
 
-from sphinx.application import Sphinx
+from typing import TYPE_CHECKING
 
 from . import docstrings, roles
 
+if TYPE_CHECKING:
+    import sphinx
 
-def setup(app: Sphinx) -> dict:
+
+def setup(app: sphinx.application.Sphinx) -> dict:
     """
     Allow this module to be used as sphinx extension.
 

sphinxcontrib_django/docstrings/__init__.py

@@ -31,12 +31,10 @@
 from .methods import improve_method_docstring
 
 if TYPE_CHECKING:
-    from sphinx.application import Sphinx
-    from sphinx.config import Config
-    from sphinx.ext.autodoc import Options
+    import sphinx
 
 
-def setup(app: Sphinx) -> dict:
+def setup(app: sphinx.application.Sphinx) -> dict:
     """
     Allow this package to be used as Sphinx extension.
 
@@ -93,7 +91,7 @@ def setup(app: Sphinx) -> dict:
     }
 
 
-def setup_django(app: Sphinx, config: Config) -> None:
+def setup_django(app: sphinx.application.Sphinx, config: sphinx.config.Config) -> None:
     """
     This function calls :func:`django.setup` so it doesn't have to be done in the app's
     ``conf.py``.
@@ -127,7 +125,12 @@ def setup_django(app: Sphinx, config: Config) -> None:
 
 
 def autodoc_skip(
-    app: Sphinx, what: str, name: str, obj: object, options: Options, lines: list[str]
+    app: sphinx.application.Sphinx,
+    what: str,
+    name: str,
+    obj: object,
+    options: sphinx.ext.autodoc.Options,
+    lines: list[str],
 ) -> bool | None:
     """
     Hook to tell autodoc to include or exclude certain fields (see :event:`autodoc-skip-member`).
@@ -151,7 +154,12 @@ def autodoc_skip(
 
 
 def improve_docstring(
-    app: Sphinx, what: str, name: str, obj: object, options: Options, lines: list[str]
+    app: sphinx.application.Sphinx,
+    what: str,
+    name: str,
+    obj: object,
+    options: sphinx.ext.autodoc.Options,
+    lines: list[str],
 ) -> list[str]:
     """
     Hook to improve the autodoc docstrings for Django models

sphinxcontrib_django/docstrings/classes.py

@@ -3,15 +3,22 @@
 """
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from django import forms
 from django.db import models
-from sphinx.application import Sphinx
 from sphinx.pycode import ModuleAnalyzer
 
 from .field_utils import get_field_type, get_field_verbose_name
 
+if TYPE_CHECKING:
+    import django
+    import sphinx
+
 
-def improve_class_docstring(app: Sphinx, cls: type, lines: list[str]) -> None:
+def improve_class_docstring(
+    app: sphinx.application.Sphinx, cls: type, lines: list[str]
+) -> None:
     """
     Improve the documentation of a class if it's a Django model or form
 
@@ -25,7 +32,9 @@ def improve_class_docstring(app: Sphinx, cls: type, lines: list[str]) -> None:
         improve_form_docstring(cls, lines)
 
 
-def improve_model_docstring(app: Sphinx, model: models.Model, lines: list[str]) -> None:
+def improve_model_docstring(
+    app: sphinx.application.Sphinx, model: django.db.models.Model, lines: list[str]
+) -> None:
     """
     Improve the documentation of a Django :class:`~django.db.models.Model` subclass.
 
@@ -109,7 +118,9 @@ def improve_model_docstring(app: Sphinx, model: models.Model, lines: list[str])
         lines.append("")
 
 
-def add_db_table_name(app: Sphinx, model: models.Model, lines: list[str]) -> None:
+def add_db_table_name(
+    app: sphinx.application.Sphinx, model: django.db.models.Model, lines: list[str]
+) -> None:
     """
     Format and add table name by extension configuration.
 
@@ -126,7 +137,7 @@ def add_db_table_name(app: Sphinx, model: models.Model, lines: list[str]) -> Non
 
 
 def add_model_parameters(
-    fields: list[models.Field], lines: list[str], field_docs: dict
+    fields: list[django.db.models.Field], lines: list[str], field_docs: dict
 ) -> None:
     """
     Add the given fields as model parameter with the ``:param:`` directive
@@ -151,7 +162,7 @@ def add_model_parameters(
         lines.append(f":type {field.name}: {get_field_type(field, include_role=False)}")
 
 
-def improve_form_docstring(form: forms.Form, lines: list[str]) -> None:
+def improve_form_docstring(form: django.forms.Form, lines: list[str]) -> None:
     """
     Improve the documentation of a Django :class:`~django.forms.Form` class.
     This highlights the available fields in the form.

sphinxcontrib_django/docstrings/field_utils.py

@@ -5,13 +5,18 @@
 """
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from django.apps import apps
 from django.contrib import contenttypes
 from django.db import models
 from django.utils.encoding import force_str
 
+if TYPE_CHECKING:
+    import django
+
 
-def get_field_type(field: models.Field, include_role: bool = True) -> str:
+def get_field_type(field: django.db.models.Field, include_role: bool = True) -> str:
     """
     Get the type of a field including the correct intersphinx mappings.
 
@@ -43,7 +48,7 @@ def get_field_type(field: models.Field, include_role: bool = True) -> str:
     return f"~{type(field).__module__}.{type(field).__name__}"
 
 
-def get_field_verbose_name(field: models.Field) -> str:
+def get_field_verbose_name(field: django.db.models.Field) -> str:
     """
     Get the verbose name of the field.
     If the field has a ``help_text``, it is also included.
@@ -133,7 +138,9 @@ def get_field_verbose_name(field: models.Field) -> str:
     return verbose_name
 
 
-def get_model_from_string(field: models.Field, model_string: str) -> type[models.Model]:
+def get_model_from_string(
+    field: django.db.models.Field, model_string: str
+) -> type[django.db.models.Model]:
     """
     Get a model class from a string
 

sphinxcontrib_django/roles.py

@@ -24,17 +24,19 @@
 from __future__ import annotations
 
 import logging
+from typing import TYPE_CHECKING
 
-from sphinx.application import Sphinx
-from sphinx.config import Config
 from sphinx.errors import ExtensionError
 
 from . import __version__
 
+if TYPE_CHECKING:
+    import sphinx
+
 logger = logging.getLogger(__name__)
 
 
-def setup(app: Sphinx) -> dict:
+def setup(app: sphinx.application.Sphinx) -> dict:
     """
     Allow this module to be used as Sphinx extension.
 
@@ -68,7 +70,9 @@ def setup(app: Sphinx) -> dict:
     }
 
 
-def add_default_intersphinx_mappings(app: Sphinx, config: Config) -> None:
+def add_default_intersphinx_mappings(
+    app: sphinx.application.Sphinx, config: sphinx.config.Config
+) -> None:
     """
     This function provides a default intersphinx mapping to the documentations of Python, Django
     and Sphinx if ``intersphinx_mapping`` is not given in ``conf.py``.