python/lib/django_1_4/docs/ref/contrib/admin/admindocs.txt

   1 ========================================
   2 The Django admin documentation generator
   3 ========================================
   4
   5 .. module:: django.contrib.admindocs
   6     :synopsis: Django's admin documentation generator.
   7
   8 .. currentmodule:: django.contrib.admindocs
   9
  10 Django's :mod:`~django.contrib.admindocs` app pulls documentation from the
  11 docstrings of models, views, template tags, and template filters for any app in
  12 :setting:`INSTALLED_APPS` and makes that documentation available from the
  13 :mod:`Django admin <django.contrib.admin>`.
  14
  15 In addition to providing offline documentation for all template tags and
  16 template filters that ship with Django, you may utilize admindocs to quickly
  17 document your own code.
  18
  19 Overview
  20 ========
  21
  22 To activate the :mod:`~django.contrib.admindocs`, you will need to do
  23 the following:
  24
  25 * Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`.
  26 * Add ``(r'^admin/doc/', include('django.contrib.admindocs.urls'))`` to
  27   your :data:`urlpatterns`. Make sure it's included *before* the
  28   ``r'^admin/'`` entry, so that requests to ``/admin/doc/`` don't get
  29   handled by the latter entry.
  30 * Install the docutils Python module (http://docutils.sf.net/).
  31 * **Optional:** Linking to templates requires the :setting:`ADMIN_FOR`
  32   setting to be configured.
  33 * **Optional:** Using the admindocs bookmarklets requires the
  34   :mod:`XViewMiddleware<django.middleware.doc>` to be installed.
  35
  36 Once those steps are complete, you can start browsing the documentation by
  37 going to your admin interface and clicking the "Documentation" link in the
  38 upper right of the page.
  39
  40 Documentation helpers
  41 =====================
  42
  43 The following special markup can be used in your docstrings to easily create
  44 hyperlinks to other components:
  45
  46 =================   =======================
  47 Django Component    reStructuredText roles
  48 =================   =======================
  49 Models              ``:model:`appname.ModelName```
  50 Views               ``:view:`appname.view_name```
  51 Template tags       ``:tag:`tagname```
  52 Template filters    ``:filter:`filtername```
  53 Templates           ``:template:`path/to/template.html```
  54 =================   =======================
  55
  56 Model reference
  57 ===============
  58
  59 The **models** section of the ``admindocs`` page describes each model in the
  60 system along with all the fields and methods available on it. Relationships to
  61 other models appear as hyperlinks. Descriptions are pulled from ``help_text``
  62 attributes on fields or from docstrings on model methods.
  63
  64 A model with useful documentation might look like this::
  65
  66     class BlogEntry(models.Model):
  67         """
  68         Stores a single blog entry, related to :model:`blog.Blog` and
  69         :model:`auth.User`.
  70
  71         """
  72         slug = models.SlugField(help_text="A short label, generally used in URLs.")
  73         author = models.ForeignKey(User)
  74         blog = models.ForeignKey(Blog)
  75         ...
  76
  77         def publish(self):
  78             """Makes the blog entry live on the site."""
  79             ...
  80
  81 View reference
  82 ==============
  83
  84 Each URL in your site has a separate entry in the ``admindocs`` page, and
  85 clicking on a given URL will show you the corresponding view. Helpful things
  86 you can document in your view function docstrings include:
  87
  88 * A short description of what the view does.
  89 * The **context**, or a list of variables available in the view's template.
  90 * The name of the template or templates that are used for that view.
  91
  92 For example::
  93
  94     from myapp.models import MyModel
  95
  96     def my_view(request, slug):
  97         """
  98         Display an individual :model:`myapp.MyModel`.
  99
 100         **Context**
 101
 102         ``RequestContext``
 103
 104         ``mymodel``
 105             An instance of :model:`myapp.MyModel`.
 106
 107         **Template:**
 108
 109         :template:`myapp/my_template.html`
 110
 111         """
 112         return render_to_response('myapp/my_template.html', {
 113             'mymodel': MyModel.objects.get(slug=slug)
 114         }, context_instance=RequestContext(request))
 115
 116
 117 Template tags and filters reference
 118 ===================================
 119
 120 The **tags** and **filters** ``admindocs`` sections describe all the tags and
 121 filters that come with Django (in fact, the :ref:`built-in tag reference
 122 <ref-templates-builtins-tags>` and :ref:`built-in filter reference
 123 <ref-templates-builtins-filters>` documentation come directly from those
 124 pages). Any tags or filters that you create or are added by a third-party app
 125 will show up in these sections as well.
 126
 127
 128 Template reference
 129 ==================
 130
 131 While ``admindocs`` does not include a place to document templates by
 132 themselves, if you use the ``:template:`path/to/template.html``` syntax in a
 133 docstring the resulting page will verify the path of that template with
 134 Django's :ref:`template loaders <template-loaders>`. This can be a handy way to
 135 check if the specified template exists and to show where on the filesystem that
 136 template is stored.
 137
 138
 139 Included Bookmarklets
 140 =====================
 141
 142 Several useful bookmarklets are available from the ``admindocs`` page:
 143
 144 Documentation for this page
 145     Jumps you from any page to the documentation for the view that generates
 146     that page.
 147
 148 Show object ID
 149     Shows the content-type and unique ID for pages that represent a single
 150     object.
 151
 152 Edit this object
 153     Jumps to the admin page for pages that represent a single object.
 154
 155 Using these bookmarklets requires that you are either logged into the
 156 :mod:`Django admin <django.contrib.admin>` as a
 157 :class:`~django.contrib.auth.models.User` with
 158 :attr:`~django.contrib.auth.models.User.is_staff` set to `True`, or
 159 that the :mod:`django.middleware.doc` middleware and
 160 :mod:`XViewMiddleware <django.middleware.doc>` are installed and you
 161 are accessing the site from an IP address listed in :setting:`INTERNAL_IPS`.