diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/contrib/admin/admindocs.txt | 161 | ||||
| -rw-r--r-- | docs/ref/contrib/admin/index.txt | 1 | ||||
| -rw-r--r-- | docs/ref/middleware.txt | 2 | ||||
| -rw-r--r-- | docs/ref/templates/builtins.txt | 4 |
4 files changed, 165 insertions, 3 deletions
diff --git a/docs/ref/contrib/admin/admindocs.txt b/docs/ref/contrib/admin/admindocs.txt new file mode 100644 index 0000000000..3aa815df2f --- /dev/null +++ b/docs/ref/contrib/admin/admindocs.txt @@ -0,0 +1,161 @@ +======================================== +The Django admin documentation generator +======================================== + +.. module:: django.contrib.admindocs + :synopsis: Django's admin documentation generator. + +.. currentmodule:: django.contrib.admindocs + +Django's :mod:`~django.contrib.admindocs` app pulls documentation from the +docstrings of models, views, template tags, and template filters for any app in +:setting:`INSTALLED_APPS` and makes that documentation available from the +:mod:`Django admin <django.contrib.admin>`. + +In addition to providing offline documentation for all template tags and +template filters that ship with Django, you may utilize admindocs to quickly +document your own code. + +Overview +======== + +To activate the :mod:`~django.contrib.admindocs`, you will need to do +the following: + + * Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`. + * Add ``(r'^admin/doc/', include('django.contrib.admindocs.urls'))`` to + your :data:`urlpatterns`. Make sure it's included *before* the + ``r'^admin/'`` entry, so that requests to ``/admin/doc/`` don't get + handled by the latter entry. + * Install the docutils Python module (http://docutils.sf.net/). + * **Optional:** Linking to templates requires the :setting:`ADMIN_FOR` + setting to be configured. + * **Optional:** Using the admindocs bookmarklets requires the + :mod:`XViewMiddleware<django.middleware.doc>` to be installed. + +Once those steps are complete, you can start browsing the documentation by +going to your admin interface and clicking the "Documentation" link in the +upper right of the page. + +Documentation helpers +===================== + +The following special markup can be used in your docstrings to easily create +hyperlinks to other components: + +================= ======================= +Django Component reStructuredText roles +================= ======================= +Models ``:model:`appname.ModelName``` +Views ``:view:`appname.view_name``` +Template tags ``:tag:`tagname``` +Template filters ``:filter:`filtername``` +Templates ``:template:`path/to/template.html``` +================= ======================= + +Model reference +=============== + +The **models** section of the ``admindocs`` page describes each model in the +system along with all the fields and methods available on it. Relationships to +other models appear as hyperlinks. Descriptions are pulled from ``help_text`` +attributes on fields or from docstrings on model methods. + +A model with useful documentation might look like this:: + + class BlogEntry(models.Model): + """ + Stores a single blog entry, related to :model:`blog.Blog` and + :model:`auth.User`. + + """ + slug = models.SlugField(help_text="A short label, generally used in URLs.") + author = models.ForeignKey(User) + blog = models.ForeignKey(Blog) + ... + + def publish(self): + """Makes the blog entry live on the site.""" + ... + +View reference +============== + +Each URL in your site has a separate entry in the ``admindocs`` page, and +clicking on a given URL will show you the corresponding view. Helpful things +you can document in your view function docstrings include: + + * A short description of what the view does. + * The **context**, or a list of variables available in the view's template. + * The name of the template or templates that are used for that view. + +For example:: + + from myapp.models import MyModel + + def my_view(request, slug): + """ + Display an individual :model:`myapp.MyModel`. + + **Context** + + ``RequestContext`` + + ``mymodel`` + An instance of :model:`myapp.MyModel`. + + **Template:** + + :template:`myapp/my_template.html` + + """ + return render_to_response('myapp/my_template.html', { + 'mymodel': MyModel.objects.get(slug=slug) + }, context_instance=RequestContext(request)) + + +Template tags and filters reference +=================================== + +The **tags** and **filters** ``admindocs`` sections describe all the tags and +filters that come with Django (in fact, the :ref:`built-in tag reference +<ref-templates-builtins-tags>` and :ref:`built-in filter reference +<ref-templates-builtins-filters>` documentation come directly from those +pages). Any tags or filters that you create or are added by a third-party app +will show up in these sections as well. + + +Template reference +================== + +While ``admindocs`` does not include a place to document templates by +themselves, if you use the ``:template:`path/to/template.html``` syntax in a +docstring the resulting page will verify the path of that template with +Django’s :ref:`template loaders <template-loaders>`. This can be a handy way to +check if the specified template exists and to show where on the filesystem that +template is stored. + + +Included Bookmarklets +===================== + +Several useful bookmarklets are available from the ``admindocs`` page: + + Documentation for this page + Jumps you from any page to the documentation for the view that generates + that page. + + Show object ID + Shows the content-type and unique ID for pages that represent a single + object. + + Edit this object + Jumps to the admin page for pages that represent a single object. + +Using these bookmarklets requires that you are either logged into the +:mod:`Django admin <django.contrib.admin>` as a +:class:`~django.contrib.auth.models.User` with +:attr:`~django.contrib.auth.models.User.is_staff` set to `True`, or +that the :mod:`django.middleware.doc` middleware and +:mod:`XViewMiddleware <django.middleware.doc>` are installed and you +are accessing the site from an IP address listed in :setting:`INTERNAL_IPS`.
\ No newline at end of file diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 055057677c..ac517e868b 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -49,6 +49,7 @@ Other topics :maxdepth: 1 actions + admindocs .. seealso:: diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index fa275d92d7..eb746e448e 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -84,7 +84,7 @@ View metadata middleware Sends custom ``X-View`` HTTP headers to HEAD requests that come from IP addresses defined in the :setting:`INTERNAL_IPS` setting. This is used by -Django's automatic documentation system. +Django's :doc:`automatic documentation system </ref/contrib/admin/admindocs>`. GZIP middleware --------------- diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 9839fc7d5c..0d66b5115b 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -3,8 +3,8 @@ Built-in template tags and filters ================================== This document describes Django's built-in template tags and filters. It is -recommended that you use the :ref:`automatic documentation -<template-built-in-reference>`, if available, as this will also include +recommended that you use the :doc:`automatic documentation +</ref/contrib/admin/admindocs>`, if available, as this will also include documentation for any custom tags or filters installed. .. _ref-templates-builtins-tags: |