timobrembeck / sphinxcontrib-django2 Goto Github PK

Intersphinx mappings to e.g. django.db.models.base.Model are not working, because the Model class is documented in the django.db.models package. This also affects some other classes:

• Members of django.contrib.postgres.forms.array and django.contrib.postgres.forms.jsonb are documented in django.contrib.postgres.forms
• Members of django.forms.forms, django.forms.fields, django.forms.models and django.forms.widgets are documented in django.forms
• Members of django.test.testcases are documented in django.test

I have encountered an error:

Extension error:
Handler <function improve_docstring at 0x7ff688d2c7b8> for event 'autodoc-process-docstring' threw an exception (exception: 'GenericForeignKey' object has no attribute 'primary_key')

Model:

from django.contrib.contenttypes.fields import GenericForeignKey

class MyModel(models.Model):
    user = ForeignKey(User, ...)
    object = GenericForeignKey('content_type', 'object_pk')
    ...

It appears to originate in the highest-level else block of get_field_verbose_name (permalink)

if isinstance(field, models.fields.reverse_related.ForeignObjectRel):
    # do stuff
else:
        # This means the field is either a normal field or a forward related field
        # If the field is a primary key, include a notice
        primary_key = "Primary key: " if field.primary_key else ""

        field_verbose_name = force_str(field.verbose_name)
        # Make the first letter upper case while leave the rest unchanged
        # (str.capitalize() would make the rest lower case, e.g. ID => Id)
        verbose_name = (
            primary_key + field_verbose_name[:1].upper() + field_verbose_name[1:]
        )
        help_text = force_str(field.help_text)

I suppose an extra type check or exception handler is needed.

The documentation of the attribute form_class in views which inherit from Django's FormView produces the following warning when executing sphinx-build:

WARNING: :1: (WARNING/2) Bullet list ends without a blank line; unexpected unindent.

It took me a while to figure out what the problem is, because there is no reference to the source code which produced this warning.
Looking at the verbose debug output of sphinx-build, I noticed the following:

   .. py:attribute:: CustomView.form_class
      :module: app.views

      Docstring for this attribute

      **Form fields:**

      * ``field1``: Field1 (:class:`~django.forms.fields.CharField`)
      alias of :class:`CustomForm`

So the form fields are appended to the docstring by sphinxcontrib-django and the "alias" is appended because the value of the field in a class. The missing new line between the bullet list and the "alias"-line causes the warning.