Handling custom field types in admindocs. (#7977)
J. Clifford Dyer
display documentation on custom field types, because it tries to pull a
human readable field type description out of a dictionary, based on the
return value of the field's get_internal_type method.
I'm working on solving this issue, and have two potential solutions. I
want to float them across this list, see if people like one or the
other. Both of them involve having Field subclasses responsible for
their own descriptions, rather than putting this information in the
admindocs views. One involves using a class attribute, and the other
relies on the Field's docstring.
CLASS ATTRIBUTES
Each subclass of Field would define a class attribute named
verbose_field_type, which is a unicode object containing a description
of what the field is. The advantage of this method is that if not
defined, the field would be able to return its superclass's
verbose_field_type. Then Field could be defined with verbose_field_type
as a property like:
@property
def verbose_field_type(self):
return _(u'Field of type: %s') % self.__class__.__name__
The admindocs app could pull this value, and if not found (e.g. if the
field doesn't subclass Field), return _(u"Unknown field type")
DOCSTRINGS
The admindocs app would populate the field using a docstring defined on
each subclass of Field. At present, Field subclasses in django's core
(django/db/models/fields/__init__.py) are all defined without
docstrings, so there isn't any risk of changing current functionality by
adding docstrings that suit this purpose.
The advantage of this method is that it is more consistent with how the
admindocs app creates other parts of its documentation. The
disadvantage is that it breaks inheritance. Each subclass of field
would need to provide its own docstring. The admindocs app could be
told to create a default '_(u'Field of type: %s') %
self.__class__.__name__ docstring, as Field did above, but intermediate
field types, such as CharField could not publish their descriptions to
subclasses as a default.
What are people's thoughts as to the merits of either approach?
J. Clifford Dyer
J. Cliff Dyer
In the absence of any other feedback, I will try implementing this using
docstrings. I think the consistency with the rest of admindocs is a
valuable feature, and on further thought I'm not sure that inheritance
is an obvious benefit here, as a subclass of a given field type is
likely being subclassed because it represents something conceptually
different. Using docstrings also provides more consistency between
different methods of obtaining documentation (pydoc vs admindocs)
Cheers,
Cliff