Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Browse files

Apply doc addition that somehow was left out of r11833. Refs #7977.

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 20938b6 commit d10dd3eceb45b72746c974adaf7d9040aa48dd0a @kmtracey kmtracey committed
Showing with 21 additions and 0 deletions.
  1. +21 −0 docs/howto/custom-model-fields.txt
21 docs/howto/custom-model-fields.txt
@@ -39,6 +39,8 @@ are traditionally called *north*, *east*, *south* and *west*. Our class looks
something like this::
class Hand(object):
+ """A hand of cards (bridge style)"""
def __init__(self, north, east, south, west):
# Input parameters are lists of cards ('Ah', '9s', etc)
self.north = north
@@ -163,6 +165,8 @@ behave like any existing field, so we'll subclass directly from
from django.db import models
class HandField(models.Field):
+ """A hand of cards (bridge style)"""
def __init__(self, *args, **kwargs):
kwargs['max_length'] = 104
super(HandField, self).__init__(*args, **kwargs)
@@ -244,6 +248,8 @@ simple: make sure your field subclass uses a special metaclass:
For example::
class HandField(models.Field):
+ """A hand of cards (bridge style)"""
__metaclass__ = models.SubfieldBase
def __init__(self, *args, **kwargs):
@@ -252,6 +258,21 @@ For example::
This ensures that the :meth:`to_python` method, documented below, will always be
called when the attribute is initialized.
+Documenting your Custom Field
+As always, you should document your field type, so users will know what it is.
+The best way to do this is to simply provide a docstring for it. This will
+automatically be picked up by ``django.contrib.admindocs``, if you have it
+installed, and the first line of it will show up as the field type in the
+documentation for any model that uses your field. In the above examples, it
+will show up as 'A hand of cards (bridge style)'. Note that if you provide a
+more verbose docstring, only the first line will show up in
+``django.contrib.admindocs``. The full docstring will, of course, still be
+available through ``pydoc`` or the interactive interpreter's ``help()``
Useful methods

0 comments on commit d10dd3e

Please sign in to comment.
Something went wrong with that request. Please try again.