python/lib/django-1.2/docs/ref/contrib/admin/admindocs.txt

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