diff options
| -rw-r--r-- | docs/howto/custom-model-fields.txt | 9 | ||||
| -rw-r--r-- | docs/index.txt | 2 | ||||
| -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 | ||||
| -rw-r--r-- | docs/topics/templates.txt | 58 |
7 files changed, 183 insertions, 54 deletions
diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index fa4c07fed2..1840c5b6f2 100644 --- a/docs/howto/custom-model-fields.txt +++ b/docs/howto/custom-model-fields.txt @@ -292,10 +292,11 @@ Documenting your Custom Field As always, you should document your field type, so users will know what it is. In addition to providing a docstring for it, which is useful for developers, you can also allow users of the admin app to see a short description of the -field type via the ``django.contrib.admindocs`` application. To do this simply -provide descriptive text in a ``description`` class attribute of your custom field. -In the above example, the type description displayed by the ``admindocs`` application -for a ``HandField`` will be 'A hand of cards (bridge style)'. +field type via the :doc:`django.contrib.admindocs +</ref/contrib/admin/admindocs>` application. To do this simply provide +descriptive text in a ``description`` class attribute of your custom field. In +the above example, the type description displayed by the ``admindocs`` +application for a ``HandField`` will be 'A hand of cards (bridge style)'. Useful methods -------------- diff --git a/docs/index.txt b/docs/index.txt index c031b03f54..d6c2d4f19e 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -161,7 +161,7 @@ The development process Other batteries included ======================== - * :doc:`Admin site <ref/contrib/admin/index>` | :doc:`Admin actions <ref/contrib/admin/actions>` + * :doc:`Admin site <ref/contrib/admin/index>` | :doc:`Admin actions <ref/contrib/admin/actions>` | :doc:`Admin documentation generator<ref/contrib/admin/admindocs>` * :doc:`Authentication <topics/auth>` * :doc:`Cache system <topics/cache>` * :doc:`Conditional content processing <topics/conditional-view-processing>` diff --git a/docs/ref/contrib/admin/admindocs.txt b/docs/ref/contrib/admin/admindocs.txt new file mode 100644 index 0000000000..882163e9eb --- /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`.
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 4a80a1593a..9313e2ffe7 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: diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt index 5586ed8c12..d249bd3ccd 100644 --- a/docs/topics/templates.txt +++ b/docs/topics/templates.txt @@ -100,9 +100,6 @@ If you use a variable that doesn't exist, the template system will insert the value of the ``TEMPLATE_STRING_IF_INVALID`` setting, which is set to ``''`` (the empty string) by default. -See `Using the built-in reference`_, below, for help on finding what variables -are available in a given template. - Filters ======= @@ -161,6 +158,12 @@ Again, these are just a few examples; see the :ref:`built-in filter reference You can also create your own custom template filters; see :doc:`/howto/custom-template-tags`. +.. seealso:: + + Django's admin interface can include a complete reference of all template + tags and filters available for a given site. See + :doc:`/ref/contrib/admin/admindocs`. + Tags ==== @@ -217,6 +220,12 @@ tag reference <ref-templates-builtins-tags>` for the complete list. You can also create your own custom template tags; see :doc:`/howto/custom-template-tags`. +.. seealso:: + + Django's admin interface can include a complete reference of all template + tags and filters available for a given site. See + :doc:`/ref/contrib/admin/admindocs`. + Comments ======== @@ -569,49 +578,6 @@ This doesn't affect what happens to data coming from the variable itself. The variable's contents are still automatically escaped, if necessary, because they're beyond the control of the template author. -.. _template-built-in-reference: - -Using the built-in reference -============================ - -Django's admin interface includes a complete reference of all template tags and -filters available for a given site. To activate it, follow these steps: - - * 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 module (http://docutils.sf.net/). - -After you've followed those steps, you can start browsing the documentation by -going to your admin interface and clicking the "Documentation" link in the -upper right of the page. - -The reference is divided into 4 sections: tags, filters, models, and views. - -The **tags** and **filters** sections describe all the built-in tags (in fact, -the tag and filter references below come directly from those pages) as well as -any custom tag or filter libraries available. - -The **views** page is the most valuable. Each URL in your site has a separate -entry here, and clicking on a URL will show you: - - * The name of the view function that generates that view. - * 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. - -Each view documentation page also has a bookmarklet that you can use to jump -from any page to the documentation page for that view. - -Because Django-powered sites usually use database objects, the **models** -section of the documentation page describes each type of object in the system -along with all the fields available on that object. - -Taken together, the documentation pages should tell you every tag, filter, -variable and object available to you in a given template. - .. _loading-custom-template-libraries: Custom tag and filter libraries |