From f4282336b3a7a8c88de524523b6044db53ea98b2 Mon Sep 17 00:00:00 2001 From: Karen Tracey Date: Wed, 16 Dec 2009 18:17:18 +0000 Subject: [1.1.X] Fixed #12385: Made built-in field type descriptions in admindocs translatable again. Many thanks to Ramiro for the problem report and patch. r11878 from trunk. git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.1.X@11879 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/howto/custom-model-fields.txt | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index f407c2bfad..1475aaf62d 100644 --- a/docs/howto/custom-model-fields.txt +++ b/docs/howto/custom-model-fields.txt @@ -5,6 +5,7 @@ Writing custom model fields =========================== .. versionadded:: 1.0 +.. currentmodule:: django.db.models Introduction ============ @@ -165,7 +166,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)""" + + description = "A hand of cards (bridge style)" def __init__(self, *args, **kwargs): kwargs['max_length'] = 104 @@ -248,7 +250,8 @@ simple: make sure your field subclass uses a special metaclass: For example:: class HandField(models.Field): - """A hand of cards (bridge style)""" + + description = "A hand of cards (bridge style)" __metaclass__ = models.SubfieldBase @@ -262,16 +265,17 @@ called when the attribute is initialized. Documenting your Custom Field ----------------------------- +.. class:: django.db.models.Field + +.. attribute:: description + 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. +In addition to providing a docstring for it, which is useful for developers, +you can also allow users of the admin app to see a short description of the +field type via the ``django.contrib.admindocs`` application. To do this simply +provide descriptive text in a ``description`` class attribute of your custom field. +In the above example, the type description displayed by the ``admindocs`` application +for a ``HandField`` will be 'A hand of cards (bridge style)'. Useful methods -------------- -- cgit v1.3