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

File 0001-Basic-admindocs-documentation.patch, 13.2 KB (added by Nathaniel Whiteinge, 14 years ago)

Updated patch to apply cleanly.

  • 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  
    292292As always, you should document your field type, so users will know what it is.
    293293In addition to providing a docstring for it, which is useful for developers,
    294294you 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)'.
     295field type via the :doc:`django.contrib.admindocs
     296</ref/contrib/admin/admindocs>` application. To do this simply provide
     297descriptive text in a ``description`` class attribute of your custom field. In
     298the above example, the type description displayed by the ``admindocs``
     299application for a ``HandField`` will be 'A hand of cards (bridge style)'.
    299300
    300301Useful methods
    301302--------------
  • docs/index.txt

    diff --git a/docs/index.txt b/docs/index.txt
    index afa2e37..f420b44 100644
    a b The development process  
    161161Other batteries included
    162162========================
    163163
    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>`
    165165    * :doc:`Authentication <topics/auth>`
    166166    * :doc:`Cache system <topics/cache>`
    167167    * :doc:`Conditional content processing <topics/conditional-view-processing>`
    Other batteries included  
    192192    * :doc:`Validators <ref/validators>`
    193193    * 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>`
    194194
    195 
    196195The Django open-source project
    197196==============================
    198197
  • 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========================================
     2The 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
     10Django's ``admindocs`` app pulls documentation from the docstrings of models,
     11views, 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
     15In addition to providing offline documentation for all template tags and
     16template filters that ship with Django, you may utilize admindocs to quickly
     17document your own code.
     18
     19
     20Overview
     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
     34After you've followed those steps, you can start browsing the documentation by
     35going to your admin interface and clicking the "Documentation" link in the
     36upper right of the page.
     37
     38Documentation helpers
     39=====================
     40
     41Use the following syntax when writing the docstrings in your own models, views,
     42and template tags and filters to easily create hyperlinks to other components.
     43
     44=================   =======================
     45Django Component    reStructuredText roles
     46=================   =======================
     47Models              ``:model:`appname.ModelName```
     48Views               ``:view:`appname.view_name```
     49Template tags       ``:tag:`tagname```
     50Template filters    ``:filter:`filtername```
     51Templates           ``:template:`path/to/template.html```
     52=================   =======================
     53
     54
     55Model reference
     56===============
     57
     58Because Django-powered sites usually use database objects, the **models**
     59section of the ``admindocs`` page describes each type of object in the system
     60along with all the fields and methods available on that object. Relationships
     61to other models appear as hyperlinks. Descriptions are pulled from
     62``help_text`` attributes on fields or from docstrings on model methods.
     63
     64For 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
     77View reference
     78==============
     79
     80Each URL in your site has a separate entry in the ``admindocs`` page and
     81clicking on an URL will show you that corresponding view. Here are a few
     82suggestions 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
     88For 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
     113Template tags and filters reference
     114===================================
     115
     116The **tags** and **filters** ``admindocs`` sections describe all the tags and
     117filters 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
     120pages). Any tags or filters that you create or are added by a third-party app
     121will show up here as well.
     122
     123
     124Template reference
     125==================
     126
     127There is not a place to document only templates using ``admindocs``. If you add
     128a hyperlink to a template from a view docstring, for example, the resulting
     129page will verify the given path of that template with Django’s :ref:`template
     130loaders <template-loaders>`. This can be a handy way to check if the specified
     131template exists and to show where on the filesystem that template is stored.
     132
     133
     134Included Bookmarklets
     135=====================
     136
     137Several useful bookmarklets are available from the ``admindocs`` page. They
     138require either that you are logged into an account with ``is_staff`` set, or
     139that :mod:`django.middleware.doc` is installed and you are accessing the site
     140from an IP address listed in :setting:`INTERNAL_IPS`.
     141
     142Documentation for this page
     143    Jumps you from any page to the documentation for the view that generates
     144    that page.
     145
     146Show object ID
     147    Shows the content-type and unique ID for pages that represent a single
     148    object.
     149
     150Edit 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  
    8484
    8585Sends custom ``X-View`` HTTP headers to HEAD requests that come from IP
    8686addresses defined in the :setting:`INTERNAL_IPS` setting. This is used by
    87 Django's automatic documentation system.
     87Django's :doc:`automatic documentation system </ref/contrib/admin/admindocs>`.
    8888
    8989GZIP middleware
    9090---------------
  • 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  
    33==================================
    44
    55This 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
     6recommended that you use the :doc:`automatic documentation
     7</ref/contrib/admin/admindocs>`, if available, as this will also include
    88documentation for any custom tags or filters installed.
    99
    1010.. _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  
    104104the value of the ``TEMPLATE_STRING_IF_INVALID`` setting, which is set to ``''``
    105105(the empty string) by default.
    106106
    107 See `Using the built-in reference`_, below, for help on finding what variables
    108 are available in a given template.
    109 
    110107Filters
    111108=======
    112109
    Again, these are just a few examples; see the :ref:`built-in filter reference  
    165162You can also create your own custom template filters; see
    166163:doc:`/howto/custom-template-tags`.
    167164
     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
    168171Tags
    169172====
    170173
    tag reference <ref-templates-builtins-tags>` for the complete list.  
    221224You can also create your own custom template tags; see
    222225:doc:`/howto/custom-template-tags`.
    223226
     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
    224233Comments
    225234========
    226235
    in the template language, it is not possible to pass arguments to method calls  
    612621accessed from within templates. Data should be calculated in views, then passed
    613622to templates for display.
    614623
    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 
    658624.. _loading-custom-template-libraries:
    659625
    660626Custom tag and filter libraries
Back to Top