Adding model-wide help text to a django model's admin form

In my django app, I would like to be able to add customized help text to the admin change form for some of my models. Note I'm not talking about the field specific help_text attribute that I can set on individual fields. For example, at the top of the change form for My_Model in My_App I'd like to be able to add some HTML that says "For additional information about My Model, see http://example.com" in order to provide a link to an internal documentation wiki.

Is there any simple way of accomplishing this, or do I need to create a custom admin form for the model? If so, can you give me an example of how I would do that?

Use the admin's fieldsets:

class MyAdmin(admin.ModelAdmin):
    fieldsets = (
        (None, {
            'fields': ('first', 'second', 'etc'),
            'description': "This is a set of fields group into a fieldset."
        }),
    )
    # Other admin settings go here...

You can have multiple fieldsets in an admin. Each can have its own title (replace the None above with the title). You can also add 'classes': ('collapse',), to a fieldset to have it start out collapsed (the wide class makes the data fields wider, and other class names mean whatever your CSS says they do).

Be careful: the description string is considered safe, so don't put any uncleaned data in there. This is done so you can put markup in there as needed (like your link), however, block formatting (like <ul> lists) will probably look wrong.

There is a fairly simple, yet underdocumented way of accomplishing this.

Define render_change_form in the Admin class

First, you need to pass extra context to your admin. To do this, you can define a render_change_form function within your admin Class, e.g.:

# admin.py
class CustomAdmin(admin.ModelAdmin):
    def render_change_form(self, request, context, *args, **kwargs):
        # here we define a custom template
        self.change_form_template = 'admin/myapp/change_form_help_text.html'
        extra = {
            'help_text': "This is a help message. Good luck filling out the form."
        }
        
        context.update(extra)
        return super(CustomAdmin, self).render_change_form(request,
            context, *args, **kwargs)

Creating a custom template

Next, you need to create that custom template (change_form_help_text.html) and extend the default 'admin/change_form.html'.

# change_form_help_text.html
{% extends 'admin/change_form.html' %}
{% block form_top %} 
{% if help_text %}<p>{{ help_text }}</p>{% endif %}
{% endblock %}

I've chosen to place this template inside templates/admin/myapp/, but this is also flexible.

---

More info available at:

http://davidmburke.com/2010/05/24/django-hack-adding-extra-data-to-admin-interface/

http://code.djangoproject.com/wiki/NewformsHOWTO#Q:HowcanIpassextracontextvariablesintomyaddandchangeviews

Besides the possibility of creating fieldsets with descriptions you can override the admin's template for the change form.

If I understand what you want the code below should do what you want.

def __init__(self, *args, **kwargs):
        super(ClassName, self).__init__(*args, **kwargs)
        if siteA:
            help_text = "foo"
        else:
            help_text = "bar"
        self.form.fields["field_name"].help_text = help_text

That's an example of using some logic to modify an overriden form. So you just put this in your ModelAdmin constructor that you overrode.

Just as an update to this question. You can do this in the model using help_text

https://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.Field.help_text

Since django 3.0 it's now possible to override the help_text of admin fields more easily:

from django.utils.translation import gettext_lazy as _

class AuthorForm(ModelForm):
    class Meta:
        model = Author
        fields = ('name', 'title', 'birth_date')
        labels = {
            'name': _('Writer'),
        }
        help_texts = {
            'name': _('Some useful help text.'),
        }
        error_messages = {
            'name': {
                'max_length': _("This writer's name is too long."),
            },
        }

https://docs.djangoproject.com/en/3.0/topics/forms/modelforms/#overriding-the-default-fields