Further changes to get docs working correctly

.flake8

@@ -1,6 +1,6 @@
 [flake8]
 select = B,B9,C,D,DAR,E,F,N,RST,W
-ignore = E203,E501,RST201,RST203,RST301,W503
+ignore = E203,E501,RST201,RST203,RST301,W503,R0903
 max-line-length = 120
 max-complexity = 10
 docstring-convention = google

docs/conf.py

@@ -1,12 +1,18 @@
 """Sphinx configuration for django-help documentation."""
 
+import inspect
+import os
 import sys
 from datetime import datetime
-from pathlib import Path
 
+import django
+from django.utils.html import strip_tags
+
+
+sys.path.insert(0, os.path.abspath(".."))
+os.environ["DJANGO_SETTINGS_MODULE"] = "example_project.settings"
+django.setup()
 
-# Add the project root directory to the Python path
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 
 # Project information
 project = "django-help"
@@ -64,13 +70,14 @@
 # Autodoc settings
 autodoc_default_options = {
     "members": True,
-    "member-order": "bysource",
     "special-members": "__init__",
-    "undoc-members": True,
     "exclude-members": "__weakref__",
 }
 autodoc_typehints = "description"
-autodoc_mock_imports = ["django"]  # Add any modules that might cause import errors during doc building
+autodoc_mock_imports = [
+    "django",
+    "translated_fields",
+]  # Add any modules that might cause import errors during doc building
 
 # Intersphinx settings
 intersphinx_mapping = {
@@ -92,3 +99,55 @@
     "substitution",
     "tasklist",
 ]
+
+
+def project_django_models(app, what, name, obj, options, lines):  # pylint: disable=W0613 disable=R0913
+    """Process Django models for autodoc.
+
+    From: https://djangosnippets.org/snippets/2533/
+    """
+    from django.db import models  # pylint: disable=C0415
+
+    # Only look at objects that inherit from Django's base model class
+    if inspect.isclass(obj) and issubclass(obj, models.Model):
+        # Grab the field list from the meta class
+        fields = obj._meta.get_fields()  # pylint: disable=W0212
+
+        for field in fields:
+            # If it's a reverse relation, skip it
+            if isinstance(
+                field,
+                (
+                    models.fields.related.ManyToOneRel,
+                    models.fields.related.ManyToManyRel,
+                    models.fields.related.OneToOneRel,
+                ),
+            ):
+                continue
+
+            # Decode and strip any html out of the field's help text
+            help_text = strip_tags(field.help_text) if hasattr(field, "help_text") else None
+
+            # Decode and capitalize the verbose name, for use if there isn't
+            # any help text
+            verbose_name = field.verbose_name if hasattr(field, "verbose_name") else ""
+
+            if help_text:
+                # Add the model field to the end of the docstring as a param
+                # using the help text as the description
+                lines.append(f":param {field.attname}: {help_text}")
+            else:
+                # Add the model field to the end of the docstring as a param
+                # using the verbose name as the description
+                lines.append(f":param {field.attname}: {verbose_name}")
+
+            # Add the field's type to the docstring
+            lines.append(f":type {field.attname}: {field.__class__.__name__}")
+
+    # Return the extended docstring
+    return lines
+
+
+def setup(app):
+    """Register the Django model processor with Sphinx."""
+    app.connect("autodoc-process-docstring", project_django_models)

docs/index.md

@@ -1,7 +1,4 @@
 ```{include} ../README.md
----
-end-before: <!-- github-only -->
----
 ```
 
 [license]: license

docs/requirements.txt

@@ -4,6 +4,7 @@ sphinx-rtd-theme==2.0.0
 sphinx-click==5.1.0
 myst-parser==2.0.0
 furo==2024.1.29
+linkify-it-py==2.0.3
 
 # Django and related packages (for autodoc)
 Django==5.0.2

noxfile.py

@@ -204,7 +204,7 @@ def docs_build(session: Session, django: str) -> None:
         args.insert(0, "--color")
 
     session.install(".")
-    session.install("sphinx", "sphinx-click", "furo", "myst-parser")
+    session.install("sphinx", "sphinx-click", "furo", "myst-parser", "linkify-it-py")
 
     build_dir = Path("docs", "_build")
     if build_dir.exists():
@@ -219,7 +219,7 @@ def docs(session: Session, django: str) -> None:
     """Build and serve the documentation with live reloading on file changes."""
     args = session.posargs or ["--open-browser", "docs", "docs/_build"]
     session.install(".")
-    session.install("sphinx", "sphinx-autobuild", "sphinx-click", "furo", "myst-parser")
+    session.install("sphinx", "sphinx-autobuild", "sphinx-click", "furo", "myst-parser", "linkify-it-py")
 
     build_dir = Path("docs", "_build")
     if build_dir.exists():

pyproject.toml

@@ -76,6 +76,7 @@ dev-dependencies = [
     "sphinx-click>=6.0.0",
     "xdoctest[colors]>=1.1.3",
     "myst-parser>=4.0.0",
+    "linkify-it-py==2.0.3",
 ]
 
 [tool.black]

src/django_help/app_settings.py

@@ -2,21 +2,23 @@
 
 Use the DJANGO_HELP_CONFIG setting to configure the app. For example:
 
-DJANGO_HELP_CONFIG = {
-    "BASE_MANAGER": "myapp.models.MyManager",
-    "BASE_QUERYSET": "myapp.models.MyQuerySet",
-    "BASE_MODEL": "myapp.models.MyModel",
-    "BASE_FOREIGN_KEY": "myapp.models.MyForeignKey",
-    "EXTRA_LANGUAGES": {
-        "es": {"blank": False},  # Spanish fields must be filled out.
-        "fr": {"blank": True},  # French fields can be left blank.
-    },
-    "AUTHORIZE_USER_TO_VIEW_ARTICLE": "myapp.utils.authorize_user_to_view_article",
-    "INTENDED_ENTITY_TYPE": {
-        "PERSON": ("person", "Person"),
-        "ORGANIZATION": ("organization", "Organization"),
-    },
-}
+.. code-block:: python
+
+    DJANGO_HELP_CONFIG = {
+        "BASE_MANAGER": "myapp.models.MyManager",
+        "BASE_QUERYSET": "myapp.models.MyQuerySet",
+        "BASE_MODEL": "myapp.models.MyModel",
+        "BASE_FOREIGN_KEY": "myapp.models.MyForeignKey",
+        "EXTRA_LANGUAGES": {
+            "es": {"blank": False},  # Spanish fields must be filled out.
+            "fr": {"blank": True},  # French fields can be left blank.
+        },
+        "AUTHORIZE_USER_TO_VIEW_ARTICLE": "myapp.utils.authorize_user_to_view_article",
+        "INTENDED_ENTITY_TYPE": {
+            "PERSON": ("person", "Person"),
+            "ORGANIZATION": ("organization", "Organization"),
+        },
+    }
 """
 
 from django.conf import settings

src/django_help/models.py

@@ -410,10 +410,10 @@ class RelevantPath(BASE_MODEL):
     """Stores a relevant path for an article.
 
     A relevant path is a path that is relevant to the article. For example, if the article is about
-    creating a new provider, then the relevant path might be /providers/create.
+    creating a new provider, then the relevant path might be `/providers/create`.
 
     Wildcards are supported. For example, if the article is about creating a new provider, then the relevant
-    path might be /providers/*.
+    path might be `/providers/*`.
     """
 
     path = models.CharField(
@@ -437,7 +437,7 @@ class Meta(BASE_MODEL.Meta if hasattr(BASE_MODEL, "Meta") else object):
         ]
 
     def __str__(self):
-        return self.path
+        return str(self.path)
 
     @property
     def is_wildcard(self):