Ticket #12975: 0002-Basic-admindocs-documentation.patch

docs/howto/custom-model-fields.txt

@@ -294 +294 @@
 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 :ref:`django.contrib.admindocs <ref-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)'.
 
 Useful methods
 --------------

docs/index.txt

@@ -161 +161 @@
 Other batteries included
 ========================
 
-    * :ref:`Admin site <ref-contrib-admin>` | :ref:`Admin actions <ref-contrib-admin-actions>`
+    * :ref:`Admin site <ref-contrib-admin>` | :ref:`Admin actions <ref-contrib-admin-actions>` | :ref:`Admin documentation generator<ref-contrib-admindocs>`
     * :ref:`Authentication <topics-auth>`
     * :ref:`Cache system <topics-cache>`
     * :ref:`Conditional content processing <topics-conditional-processing>`

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

@@ +1 @@
+.. _ref-contrib-admindocs:
+
+========================================
+The Django admin documentation generator
+========================================
+
+.. module:: django.contrib.admindocs
+    :synopsis: Django's admin documentation generator.
+
+.. currentmodule:: django.contrib.admindocs
+
+Django's ``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>`. You may utilize this to quickly
+document your own code using the rich markup provided by reStructuredText.
+
+
+Overview
+========
+
+    * 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.
+
+Documentation helpers
+=====================
+
+Use the following syntax when writing the docstrings in your own models, views,
+and template tags and filters 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
+===============
+
+Because Django-powered sites usually use database objects, the **models**
+section of the ``admindocs`` page describes each type of object in the system
+along with all the fields and methods available on that object. Relationships
+to other models appear as hyperlinks. Descriptions are pulled from
+``help_text`` attributes on fields or docstrings from model methods.
+
+For example::
+
+    from django.db import models
+
+    class MyModel(models.Model):
+        """
+        Stores the URL and author of something.
+
+        """
+        slug = models.SlugField(help_text="The URL of the page.")
+        author = models.ForeignKey('auth.User')
+
+
+View reference
+==============
+
+Each URL in your site has a separate entry in the ``admindocs`` page and
+clicking on an URL will show you that corresponding view. Here are a few
+suggestions of helpful things you can document in your view docstrings:
+
+    * 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 here as well.
+
+
+Template reference
+==================
+
+There is not a place to document only templates using ``admindocs``. If you add
+a hyperlink to a template from a view docstring, for example, the resulting
+page will verify the given 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. They
+require either that you are logged into an account with ``is_staff`` set, or
+that :mod:`django.middleware.doc` is installed and you are accessing the site
+from an IP address listed in :setting:`INTERNAL_IPS`.
+
+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.
+
+.. vim:filetype=rst

docs/ref/middleware.txt

@@ -83 +83 @@
 
 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 :ref:`automatic documentation system <ref-contrib-admindocs>`.
 
 GZIP middleware
 ---------------

docs/ref/templates/builtins.txt

@@ -6 +6 @@
 
 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
+<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

@@ -102 +102 @@
 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
 =======
 
@@ -163 +160 @@
 You can also create your own custom template filters; see
 :ref:`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
+    :ref:`ref-contrib-admindocs`.
+
 Tags
 ====
 
@@ -219 +222 @@
 You can also create your own custom template tags; see
 :ref:`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
+    :ref:`ref-contrib-admindocs`.
+
 Comments
 ========
 
@@ -571 +580 @@
 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