Fixed #12975 -- Moved the docs for contrib.admindocs out of the template docs and into their own reference section, and significantly improved the documentation of what admindocs can do. Thanks to jabapyth for the report, and whiteinge for the patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14484 bcc190cf-cafb-0310-a4f2-bffc1f526a37

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
+field type via the :doc:`django.contrib.admindocs
-provide descriptive text in a ``description`` class attribute of your custom field.
+</ref/contrib/admin/admindocs>` application. To do this simply provide
-In the above example, the type description displayed by the ``admindocs`` application
+descriptive text in a ``description`` class attribute of your custom field. In
-for a ``HandField`` will be 'A hand of cards (bridge style)'.
+the above example, the type description displayed by the ``admindocs``
+application for a ``HandField`` will be 'A hand of cards (bridge style)'.
 
 Useful methods
 --------------

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>`
@@ -192,7 +192,6 @@ Other batteries included
     * :doc:`Validators <ref/validators>`
     * Function-based generic views (Deprecated) :doc:`Overview<topics/generic-views>` | :doc:`Built-in generic views<ref/generic-views>` | :doc:`Migration guide<topics/generic-views-migration>`
 
-
 The Django open-source project
 ==============================
 

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`.

docs/ref/contrib/admin/index.txt

@@ -49,6 +49,7 @@ Other topics
    :maxdepth: 1
 
    actions
+   admindocs
 
 .. seealso::
 

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
 ---------------

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
+recommended that you use the :doc:`automatic documentation
-<template-built-in-reference>`, if available, as this will also include
+</ref/contrib/admin/admindocs>`, if available, as this will also include
 documentation for any custom tags or filters installed.
 
 .. _ref-templates-builtins-tags:

docs/topics/templates.txt

@@ -104,9 +104,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
 =======
 
@@ -165,6 +162,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
 ====
 
@@ -221,6 +224,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
 ========
 
@@ -612,49 +621,6 @@ in the template language, it is not possible to pass arguments to method calls
 accessed from within templates. Data should be calculated in views, then passed
 to templates for display.
 
-.. _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