Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[1.1.X] Apply doc addition that somehow was left out of r11834. Refs …

…#7977.

r11841 from trunk.


git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.1.X@11842 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit b5ffd10547e941a8514eae23bc1dc1ee908d2ff2 1 parent 08b5d95
@kmtracey kmtracey authored
Showing with 21 additions and 0 deletions.
  1. +21 −0 docs/howto/custom-model-fields.txt
View
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()``
+function.
+
Useful methods
--------------
Please sign in to comment.
Something went wrong with that request. Please try again.