Merge pull request #33 from edoburu/bugfix/multi-line-docstring

Fix rendering of nested directives in model parameter documentation

Author: timobrembeck

.pre-commit-config.yaml

@@ -1,14 +1,14 @@
 repos:
   - repo: https://github.com/psf/black
-    rev: 22.10.0
+    rev: 23.1.0
     hooks:
       - id: black
   - repo: https://github.com/PyCQA/isort
-    rev: 5.10.1
+    rev: 5.12.0
     hooks:
       - id: isort
   - repo: https://github.com/pycqa/flake8
-    rev: 5.0.4
+    rev: 6.0.0
     hooks:
       - id: flake8
         additional_dependencies:

CHANGES.rst

@@ -1,6 +1,12 @@
 Changelog
 =========
 
+Unreleased
+----------
+
+* [ `#32 <https://github.com/edoburu/sphinxcontrib-django/issues/32>`_ ] Fix rendering of nested directives in model parameter documentation
+
+
 Version 2.0 (2023-01-02)
 ------------------------
 

pyproject.toml

@@ -52,7 +52,7 @@
             "django-phonenumber-field[phonenumbers]",
             "psycopg2-binary",
         ]
-        test = ["coverage", "pytest", "requests-mock"]
+        test = ["coverage", "pytest", "pytest-icdiff", "requests-mock"]
 
 [tool.setuptools.dynamic]
     version = { attr = "sphinxcontrib_django.__version__" }
@@ -62,13 +62,14 @@
 
 [tool.black]
     skip-magic-trailing-comma = true
+    preview = true
 
 [tool.coverage.run]
     command_line = "-m pytest"
     source       = ["sphinxcontrib_django"]
 
 [tool.pytest.ini_options]
-    addopts    = "-ra -q"
+    addopts    = "-ra -vv --color=yes"
     minversion = "6.0"
     testpaths  = ["tests"]
 

sphinxcontrib_django/docstrings/__init__.py

@@ -98,16 +98,16 @@ def setup_django(app, config):
     """
     if not config.django_settings:
         raise ConfigError(
-            "Please specify your Django settings in the configuration 'django_settings' in your "
-            "conf.py"
+            "Please specify your Django settings in the configuration 'django_settings'"
+            " in your conf.py"
         )
     try:
         importlib.import_module(config.django_settings)
     except ModuleNotFoundError as e:
         raise ConfigError(
-            "The module you specified in the configuration 'django_settings' in your conf.py "
-            "cannot be imported. Make sure the module path is correct and the source directoy is "
-            "added to sys.path."
+            "The module you specified in the configuration 'django_settings' in your"
+            " conf.py cannot be imported. Make sure the module path is correct and the"
+            " source directoy is added to sys.path."
         ) from e
     os.environ["DJANGO_SETTINGS_MODULE"] = config.django_settings
     django.setup()

sphinxcontrib_django/docstrings/classes.py

@@ -86,7 +86,7 @@ def improve_model_docstring(app, model, lines):
     analyzer = ModuleAnalyzer.for_module(model.__module__)
     analyzer.analyze()
     field_docs = {
-        field_name: ". " + " ".join(field_docstring).strip()
+        field_name: field_docstring
         for (_, field_name), field_docstring in analyzer.attr_docs.items()
     }
 
@@ -131,8 +131,15 @@ def add_model_parameters(fields, lines, field_docs):
     """
     for field in fields:
         # Add docstrings if they are found
-        docstring = field_docs.get(field.name, "")
-        lines.append(f":param {field.name}: {get_field_verbose_name(field)}{docstring}")
+        docstring_lines = field_docs.get(field.name, [])
+        # Add param doc line
+        param = f":param {field.name}: "
+        lines.append(param + get_field_verbose_name(field))
+        if docstring_lines:
+            # Separate from verbose name
+            lines.append("")
+        # Add and indent existing docstring lines
+        lines.extend([(" " * len(param)) + line for line in docstring_lines])
 
         # Add type
         lines.append(f":type {field.name}: {get_field_type(field, include_role=False)}")

sphinxcontrib_django/docstrings/field_utils.py

@@ -28,14 +28,15 @@ def get_field_type(field, include_role=True):
             # This happens with foreign keys of abstract models
             to = get_model_from_string(field, to)
         return (
-            f":class:`~{type(field).__module__}.{type(field).__name__}` to "
-            f":class:`~{to.__module__}.{to.__name__}`"
+            f":class:`~{type(field).__module__}.{type(field).__name__}` to"
+            f" :class:`~{to.__module__}.{to.__name__}`"
         )
     elif isinstance(field, models.fields.reverse_related.ForeignObjectRel):
         to = field.remote_field.model
         return (
-            f"Reverse :class:`~{type(field.remote_field).__module__}."
-            f"{type(field.remote_field).__name__}` from :class:`~{to.__module__}.{to.__name__}`"
+            "Reverse"
+            f" :class:`~{type(field.remote_field).__module__}.{type(field.remote_field).__name__}`"
+            f" from :class:`~{to.__module__}.{to.__name__}`"
         )
     else:
         if include_role:
@@ -92,9 +93,9 @@ def get_field_verbose_name(field):
     ):
         # GenericForeignKey does not inherit from django.db.models.Field and has no verbose_name
         return (
-            f"Generic foreign key to the :class:`~django.contrib.contenttypes.models.ContentType` "
-            f"specified in "
-            f":attr:`~{field.model.__module__}.{field.model.__name__}.{field.ct_field}`"
+            "Generic foreign key to the"
+            " :class:`~django.contrib.contenttypes.models.ContentType` specified in"
+            f" :attr:`~{field.model.__module__}.{field.model.__name__}.{field.ct_field}`"
         )
     else:
         # This means the field is either a normal field or a forward related field
@@ -131,8 +132,8 @@ def get_field_verbose_name(field):
         # Link to the related field if it's not an abstract model
         if not field.model._meta.abstract:
             verbose_name += (
-                " (related name: "
-                f":attr:`~{to.__module__}.{to.__name__}.{related_name}`)"
+                " (related name:"
+                f" :attr:`~{to.__module__}.{to.__name__}.{related_name}`)"
             )
     return verbose_name
 

sphinxcontrib_django/docstrings/methods.py

@@ -29,21 +29,23 @@ def improve_method_docstring(name, lines):
             if match is not None:
                 # Django get_..._display method
                 lines.append(
-                    f"Shows the label of the :attr:`{match.group('field')}`. "
-                    f"See :meth:`~django.db.models.Model.get_FOO_display` for more information."
+                    f"Shows the label of the :attr:`{match.group('field')}`. See"
+                    " :meth:`~django.db.models.Model.get_FOO_display` for more"
+                    " information."
                 )
         elif ".get_next_by_" in name:
             match = RE_GET_NEXT_BY.search(name)
             if match is not None:
                 lines.append(
-                    f"Finds next instance based on :attr:`{match.group('field')}`. "
-                    f"See :meth:`~django.db.models.Model.get_next_by_FOO` for more information."
+                    f"Finds next instance based on :attr:`{match.group('field')}`. See"
+                    " :meth:`~django.db.models.Model.get_next_by_FOO` for more"
+                    " information."
                 )
         elif ".get_previous_by_" in name:
             match = RE_GET_PREVIOUS_BY.search(name)
             if match is not None:
                 lines.append(
-                    f"Finds previous instance based on :attr:`{match.group('field')}`. "
-                    f"See :meth:`~django.db.models.Model.get_previous_by_FOO` for more "
-                    f"information."
+                    f"Finds previous instance based on :attr:`{match.group('field')}`."
+                    " See :meth:`~django.db.models.Model.get_previous_by_FOO` for more"
+                    " information."
                 )

tests/roots/test-docstrings/dummy_django_app/models.py

@@ -32,10 +32,20 @@ class SimpleModel(models.Model):
         "ChildModelA", related_name="simple_model", on_delete=models.CASCADE
     )
 
-    #: Docstring of many to many field
     childrenB = models.ManyToManyField("ChildModelB", related_name="simple_models")
+    """
+    Docstring of many to many field
+
+    .. note::
+
+        This syntax is also supported.
+    """
 
     #: Docstring of char field
+    #:
+    #: .. warning::
+    #:
+    #:     Inline directives should be preserved.
     dummy_field = models.CharField(
         max_length=3,
         help_text="This should help you",