Ticket #12975: 0001-Basic-admindocs-documentation.patch
| File 0001-Basic-admindocs-documentation.patch, 13.2 KB (added by , 14 years ago) |
|---|
-
docs/howto/custom-model-fields.txt
From 053c8aa85a92e4f6db9b3cf24668a676e782247e Mon Sep 17 00:00:00 2001 From: Seth House <seth@eseth.com> Date: Sun, 27 Jun 2010 11:49:26 -0600 Subject: [PATCH] Basic admindocs documentation Moved the brief mention of admindocs from the template tags documentation into a standalone section and added more detail. --- docs/howto/custom-model-fields.txt | 9 +- docs/index.txt | 3 +- docs/ref/contrib/admin/admindocs.txt | 151 ++++++++++++++++++++++++++++++++++ docs/ref/middleware.txt | 2 +- docs/ref/templates/builtins.txt | 4 +- docs/topics/templates.txt | 58 +++---------- 6 files changed, 172 insertions(+), 55 deletions(-) create mode 100644 docs/ref/contrib/admin/admindocs.txt diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index fa4c07f..1840c5b 100644
a b 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 -------------- -
docs/index.txt
diff --git a/docs/index.txt b/docs/index.txt index afa2e37..f420b44 100644
a b 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>` … … 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 -
new file docs/ref/contrib/admin/admindocs.txt
diff --git a/docs/ref/contrib/admin/admindocs.txt b/docs/ref/contrib/admin/admindocs.txt new file mode 100644 index 0000000..a6fab0d
- + 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 ``admindocs`` app pulls documentation from the docstrings of models, 11 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 20 Overview 21 ======== 22 23 * Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`. 24 * Add ``(r'^admin/doc/', include('django.contrib.admindocs.urls'))`` to 25 your :data:`urlpatterns`. Make sure it's included *before* the 26 ``r'^admin/'`` entry, so that requests to ``/admin/doc/`` don't get 27 handled by the latter entry. 28 * Install the docutils Python module (http://docutils.sf.net/). 29 * **Optional:** Linking to templates requires the :setting:`ADMIN_FOR` 30 setting to be configured. 31 * **Optional:** Using the admindocs bookmarklets requires the 32 :mod:`XViewMiddleware<django.middleware.doc>` to be installed. 33 34 After you've followed those steps, you can start browsing the documentation by 35 going to your admin interface and clicking the "Documentation" link in the 36 upper right of the page. 37 38 Documentation helpers 39 ===================== 40 41 Use the following syntax when writing the docstrings in your own models, views, 42 and template tags and filters to easily create hyperlinks to other components. 43 44 ================= ======================= 45 Django Component reStructuredText roles 46 ================= ======================= 47 Models ``:model:`appname.ModelName``` 48 Views ``:view:`appname.view_name``` 49 Template tags ``:tag:`tagname``` 50 Template filters ``:filter:`filtername``` 51 Templates ``:template:`path/to/template.html``` 52 ================= ======================= 53 54 55 Model reference 56 =============== 57 58 Because Django-powered sites usually use database objects, the **models** 59 section of the ``admindocs`` page describes each type of object in the system 60 along with all the fields and methods available on that object. Relationships 61 to other models appear as hyperlinks. Descriptions are pulled from 62 ``help_text`` attributes on fields or from docstrings on model methods. 63 64 For example:: 65 66 from django.db import models 67 68 class MyModel(models.Model): 69 """ 70 Stores the URL and author of something. 71 72 """ 73 slug = models.SlugField(help_text="The URL of the thing.") 74 author = models.ForeignKey('auth.User') 75 76 77 View reference 78 ============== 79 80 Each URL in your site has a separate entry in the ``admindocs`` page and 81 clicking on an URL will show you that corresponding view. Here are a few 82 suggestions of helpful things you can document in your view docstrings: 83 84 * A short description of what the view does. 85 * The **context**, or a list of variables available in the view's template. 86 * The name of the template or templates that are used for that view. 87 88 For example:: 89 90 from myapp.models import MyModel 91 92 def my_view(request, slug): 93 """ 94 Display an individual :model:`myapp.MyModel`. 95 96 **Context** 97 98 ``RequestContext`` 99 100 ``mymodel`` 101 An instance of :model:`myapp.MyModel`. 102 103 **Template:** 104 105 :template:`myapp/my_template.html` 106 107 """ 108 return render_to_response('myapp/my_template.html', { 109 'mymodel': MyModel.objects.get(slug=slug) 110 }, context_instance=RequestContext(request)) 111 112 113 Template tags and filters reference 114 =================================== 115 116 The **tags** and **filters** ``admindocs`` sections describe all the tags and 117 filters that come with Django (in fact, the :ref:`built-in tag reference 118 <ref-templates-builtins-tags>` and :ref:`built-in filter reference 119 <ref-templates-builtins-filters>` documentation come directly from those 120 pages). Any tags or filters that you create or are added by a third-party app 121 will show up here as well. 122 123 124 Template reference 125 ================== 126 127 There is not a place to document only templates using ``admindocs``. If you add 128 a hyperlink to a template from a view docstring, for example, the resulting 129 page will verify the given path of that template with Django’s :ref:`template 130 loaders <template-loaders>`. This can be a handy way to check if the specified 131 template exists and to show where on the filesystem that template is stored. 132 133 134 Included Bookmarklets 135 ===================== 136 137 Several useful bookmarklets are available from the ``admindocs`` page. They 138 require either that you are logged into an account with ``is_staff`` set, or 139 that :mod:`django.middleware.doc` is installed and you are accessing the site 140 from an IP address listed in :setting:`INTERNAL_IPS`. 141 142 Documentation for this page 143 Jumps you from any page to the documentation for the view that generates 144 that page. 145 146 Show object ID 147 Shows the content-type and unique ID for pages that represent a single 148 object. 149 150 Edit this object 151 Jumps to the admin page for pages that represent a single object. -
docs/ref/middleware.txt
diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index fa275d9..eb746e4 100644
a b 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 --------------- -
docs/ref/templates/builtins.txt
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 9839fc7..0d66b51 100644
a b 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 documentation7 < template-built-in-reference>`, if available, as this will also include6 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: -
docs/topics/templates.txt
diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt index fb04a3a..e180bcc 100644
a b 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 variables108 are available in a given template.109 110 107 Filters 111 108 ======= 112 109 … … 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 … … 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 … … 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 reference618 ============================619 620 Django's admin interface includes a complete reference of all template tags and621 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 your625 :data:`urlpatterns`. Make sure it's included *before* the ``r'^admin/'``626 entry, so that requests to ``/admin/doc/`` don't get handled by the627 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 by631 going to your admin interface and clicking the "Documentation" link in the632 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 as638 any custom tag or filter libraries available.639 640 The **views** page is the most valuable. Each URL in your site has a separate641 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 jump649 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 system653 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