PageRenderTime 93ms CodeModel.GetById 71ms app.highlight 1ms RepoModel.GetById 19ms app.codeStats 0ms

/docs/ref/contrib/admin/admindocs.txt

https://code.google.com/p/mango-py/
Plain Text | 161 lines | 119 code | 42 blank | 0 comment | 0 complexity | 8491cb81bf0a6c450163b89e3799b775 MD5 | raw file
  1========================================
  2The 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
 10Django's :mod:`~django.contrib.admindocs` app pulls documentation from the
 11docstrings 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
 15In addition to providing offline documentation for all template tags and
 16template filters that ship with Django, you may utilize admindocs to quickly
 17document your own code.
 18
 19Overview
 20========
 21
 22To activate the :mod:`~django.contrib.admindocs`, you will need to do
 23the 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
 36Once those steps are complete, you can start browsing the documentation by
 37going to your admin interface and clicking the "Documentation" link in the
 38upper right of the page.
 39
 40Documentation helpers
 41=====================
 42
 43The following special markup can be used in your docstrings to easily create
 44hyperlinks to other components:
 45
 46=================   =======================
 47Django Component    reStructuredText roles
 48=================   =======================
 49Models              ``:model:`appname.ModelName```
 50Views               ``:view:`appname.view_name```
 51Template tags       ``:tag:`tagname```
 52Template filters    ``:filter:`filtername```
 53Templates           ``:template:`path/to/template.html```
 54=================   =======================
 55
 56Model reference
 57===============
 58
 59The **models** section of the ``admindocs`` page describes each model in the
 60system along with all the fields and methods available on it. Relationships to
 61other models appear as hyperlinks. Descriptions are pulled from ``help_text``
 62attributes on fields or from docstrings on model methods.
 63
 64A 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
 81View reference
 82==============
 83
 84Each URL in your site has a separate entry in the ``admindocs`` page, and
 85clicking on a given URL will show you the corresponding view. Helpful things
 86you 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
 92For 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
117Template tags and filters reference
118===================================
119
120The **tags** and **filters** ``admindocs`` sections describe all the tags and
121filters 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
124pages). Any tags or filters that you create or are added by a third-party app
125will show up in these sections as well.
126
127
128Template reference
129==================
130
131While ``admindocs`` does not include a place to document templates by
132themselves, if you use the ``:template:`path/to/template.html``` syntax in a
133docstring the resulting page will verify the path of that template with
134Django's :ref:`template loaders <template-loaders>`. This can be a handy way to
135check if the specified template exists and to show where on the filesystem that
136template is stored.
137
138
139Included Bookmarklets
140=====================
141
142Several 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
155Using 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
159that the :mod:`django.middleware.doc` middleware and
160:mod:`XViewMiddleware <django.middleware.doc>` are installed and you
161are accessing the site from an IP address listed in :setting:`INTERNAL_IPS`.