Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #12975 -- Moved the docs for contrib.admindocs out of the templ…

…ate 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
  • Loading branch information...
commit 682f4cf9ed644492bad96bc6d2549cb2fe3d335f 1 parent 7f2b360
authored November 07, 2010
9  docs/howto/custom-model-fields.txt
@@ -292,10 +292,11 @@ Documenting your Custom Field
292 292
 As always, you should document your field type, so users will know what it is.
293 293
 In addition to providing a docstring for it, which is useful for developers,
294 294
 you can also allow users of the admin app to see a short description of the
295  
-field type via the ``django.contrib.admindocs`` application. To do this simply
296  
-provide descriptive text in a ``description`` class attribute of your custom field.
297  
-In the above example, the type description displayed by the ``admindocs`` application
298  
-for a ``HandField`` will be 'A hand of cards (bridge style)'.
  295
+field type via the :doc:`django.contrib.admindocs
  296
+</ref/contrib/admin/admindocs>` application. To do this simply provide
  297
+descriptive text in a ``description`` class attribute of your custom field. In
  298
+the above example, the type description displayed by the ``admindocs``
  299
+application for a ``HandField`` will be 'A hand of cards (bridge style)'.
299 300
 
300 301
 Useful methods
301 302
 --------------
3  docs/index.txt
@@ -161,7 +161,7 @@ The development process
161 161
 Other batteries included
162 162
 ========================
163 163
 
164  
-    * :doc:`Admin site <ref/contrib/admin/index>` | :doc:`Admin actions <ref/contrib/admin/actions>`
  164
+    * :doc:`Admin site <ref/contrib/admin/index>` | :doc:`Admin actions <ref/contrib/admin/actions>` | :doc:`Admin documentation generator<ref/contrib/admin/admindocs>`
165 165
     * :doc:`Authentication <topics/auth>`
166 166
     * :doc:`Cache system <topics/cache>`
167 167
     * :doc:`Conditional content processing <topics/conditional-view-processing>`
@@ -192,7 +192,6 @@ Other batteries included
192 192
     * :doc:`Validators <ref/validators>`
193 193
     * 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>`
194 194
 
195  
-
196 195
 The Django open-source project
197 196
 ==============================
198 197
 
161  docs/ref/contrib/admin/admindocs.txt
... ...
@@ -0,0 +1,161 @@
  1
+========================================
  2
+The 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
+
  10
+Django's :mod:`~django.contrib.admindocs` app pulls documentation from the
  11
+docstrings 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
+
  15
+In addition to providing offline documentation for all template tags and
  16
+template filters that ship with Django, you may utilize admindocs to quickly
  17
+document your own code.
  18
+
  19
+Overview
  20
+========
  21
+
  22
+To activate the :mod:`~django.contrib.admindocs`, you will need to do
  23
+the 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
+
  36
+Once those steps are complete, you can start browsing the documentation by
  37
+going to your admin interface and clicking the "Documentation" link in the
  38
+upper right of the page.
  39
+
  40
+Documentation helpers
  41
+=====================
  42
+
  43
+The following special markup can be used in your docstrings to easily create
  44
+hyperlinks to other components:
  45
+
  46
+=================   =======================
  47
+Django Component    reStructuredText roles
  48
+=================   =======================
  49
+Models              ``:model:`appname.ModelName```
  50
+Views               ``:view:`appname.view_name```
  51
+Template tags       ``:tag:`tagname```
  52
+Template filters    ``:filter:`filtername```
  53
+Templates           ``:template:`path/to/template.html```
  54
+=================   =======================
  55
+
  56
+Model reference
  57
+===============
  58
+
  59
+The **models** section of the ``admindocs`` page describes each model in the
  60
+system along with all the fields and methods available on it. Relationships to
  61
+other models appear as hyperlinks. Descriptions are pulled from ``help_text``
  62
+attributes on fields or from docstrings on model methods.
  63
+
  64
+A 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
+
  81
+View reference
  82
+==============
  83
+
  84
+Each URL in your site has a separate entry in the ``admindocs`` page, and
  85
+clicking on a given URL will show you the corresponding view. Helpful things
  86
+you 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
+
  92
+For 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
+
  117
+Template tags and filters reference
  118
+===================================
  119
+
  120
+The **tags** and **filters** ``admindocs`` sections describe all the tags and
  121
+filters 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
  124
+pages). Any tags or filters that you create or are added by a third-party app
  125
+will show up in these sections as well.
  126
+
  127
+
  128
+Template reference
  129
+==================
  130
+
  131
+While ``admindocs`` does not include a place to document templates by
  132
+themselves, if you use the ``:template:`path/to/template.html``` syntax in a
  133
+docstring the resulting page will verify the path of that template with
  134
+Django’s :ref:`template loaders <template-loaders>`. This can be a handy way to
  135
+check if the specified template exists and to show where on the filesystem that
  136
+template is stored.
  137
+
  138
+
  139
+Included Bookmarklets
  140
+=====================
  141
+
  142
+Several 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
+
  155
+Using 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
  159
+that the :mod:`django.middleware.doc` middleware and
  160
+:mod:`XViewMiddleware <django.middleware.doc>` are installed and you
  161
+are accessing the site from an IP address listed in :setting:`INTERNAL_IPS`.
1  docs/ref/contrib/admin/index.txt
@@ -49,6 +49,7 @@ Other topics
49 49
    :maxdepth: 1
50 50
 
51 51
    actions
  52
+   admindocs
52 53
 
53 54
 .. seealso::
54 55
 
2  docs/ref/middleware.txt
@@ -84,7 +84,7 @@ View metadata middleware
84 84
 
85 85
 Sends custom ``X-View`` HTTP headers to HEAD requests that come from IP
86 86
 addresses defined in the :setting:`INTERNAL_IPS` setting. This is used by
87  
-Django's automatic documentation system.
  87
+Django's :doc:`automatic documentation system </ref/contrib/admin/admindocs>`.
88 88
 
89 89
 GZIP middleware
90 90
 ---------------
4  docs/ref/templates/builtins.txt
@@ -3,8 +3,8 @@ Built-in template tags and filters
3 3
 ==================================
4 4
 
5 5
 This document describes Django's built-in template tags and filters. It is
6  
-recommended that you use the :ref:`automatic documentation
7  
-<template-built-in-reference>`, if available, as this will also include
  6
+recommended that you use the :doc:`automatic documentation
  7
+</ref/contrib/admin/admindocs>`, if available, as this will also include
8 8
 documentation for any custom tags or filters installed.
9 9
 
10 10
 .. _ref-templates-builtins-tags:
58  docs/topics/templates.txt
@@ -104,9 +104,6 @@ If you use a variable that doesn't exist, the template system will insert
104 104
 the value of the ``TEMPLATE_STRING_IF_INVALID`` setting, which is set to ``''``
105 105
 (the empty string) by default.
106 106
 
107  
-See `Using the built-in reference`_, below, for help on finding what variables
108  
-are available in a given template.
109  
-
110 107
 Filters
111 108
 =======
112 109
 
@@ -165,6 +162,12 @@ Again, these are just a few examples; see the :ref:`built-in filter reference
165 162
 You can also create your own custom template filters; see
166 163
 :doc:`/howto/custom-template-tags`.
167 164
 
  165
+.. seealso::
  166
+
  167
+    Django's admin interface can include a complete reference of all template
  168
+    tags and filters available for a given site. See
  169
+    :doc:`/ref/contrib/admin/admindocs`.
  170
+
168 171
 Tags
169 172
 ====
170 173
 
@@ -221,6 +224,12 @@ tag reference <ref-templates-builtins-tags>` for the complete list.
221 224
 You can also create your own custom template tags; see
222 225
 :doc:`/howto/custom-template-tags`.
223 226
 
  227
+.. seealso::
  228
+
  229
+    Django's admin interface can include a complete reference of all template
  230
+    tags and filters available for a given site. See
  231
+    :doc:`/ref/contrib/admin/admindocs`.
  232
+
224 233
 Comments
225 234
 ========
226 235
 
@@ -612,49 +621,6 @@ in the template language, it is not possible to pass arguments to method calls
612 621
 accessed from within templates. Data should be calculated in views, then passed
613 622
 to templates for display.
614 623
 
615  
-.. _template-built-in-reference:
616  
-
617  
-Using the built-in reference
618  
-============================
619  
-
620  
-Django's admin interface includes a complete reference of all template tags and
621  
-filters available for a given site. To activate it, follow these steps:
622  
-
623  
-    * Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`.
624  
-    * Add ``(r'^admin/doc/', include('django.contrib.admindocs.urls'))`` to your
625  
-      :data:`urlpatterns`. Make sure it's included *before* the ``r'^admin/'``
626  
-      entry, so that requests to ``/admin/doc/`` don't get handled by the
627  
-      latter entry.
628  
-    * Install the docutils module (http://docutils.sf.net/).
629  
-
630  
-After you've followed those steps, you can start browsing the documentation by
631  
-going to your admin interface and clicking the "Documentation" link in the
632  
-upper right of the page.
633  
-
634  
-The reference is divided into 4 sections: tags, filters, models, and views.
635  
-
636  
-The **tags** and **filters** sections describe all the built-in tags (in fact,
637  
-the tag and filter references below come directly from those pages) as well as
638  
-any custom tag or filter libraries available.
639  
-
640  
-The **views** page is the most valuable. Each URL in your site has a separate
641  
-entry here, and clicking on a URL will show you:
642  
-
643  
-    * The name of the view function that generates that view.
644  
-    * A short description of what the view does.
645  
-    * The **context**, or a list of variables available in the view's template.
646  
-    * The name of the template or templates that are used for that view.
647  
-
648  
-Each view documentation page also has a bookmarklet that you can use to jump
649  
-from any page to the documentation page for that view.
650  
-
651  
-Because Django-powered sites usually use database objects, the **models**
652  
-section of the documentation page describes each type of object in the system
653  
-along with all the fields available on that object.
654  
-
655  
-Taken together, the documentation pages should tell you every tag, filter,
656  
-variable and object available to you in a given template.
657  
-
658 624
 .. _loading-custom-template-libraries:
659 625
 
660 626
 Custom tag and filter libraries

0 notes on commit 682f4cf

Please sign in to comment.
Something went wrong with that request. Please try again.