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

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

Initial stab at documentation for the admindocs app.

  • docs/howto/custom-model-fields.txt 

    From 85dbed86f12cc39120153fc1c49aeeb69d3360d9 Mon Sep 17 00:00:00 2001
From: Seth House <seth@eseth.com>
Date: Sun, 27 Jun 2010 11:49:26 -0600
Subject: [PATCH 2/2] Basic admindocs documentation.

---
 docs/howto/custom-model-fields.txt   |    9 +-
 docs/index.txt                       |    2 +-
 docs/ref/contrib/admin/admindocs.txt |  148 ++++++++++++++++++++++++++++++++++
 docs/ref/middleware.txt              |    2 +-
 docs/ref/templates/builtins.txt      |    2 +-
 docs/topics/templates.txt            |   58 +++-----------
 6 files changed, 168 insertions(+), 53 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 9085145..3ae4c7e 100644
    a b Documenting your Custom Field  
    294294As always, you should document your field type, so users will know what it is.
    295295In addition to providing a docstring for it, which is useful for developers,
    296296you can also allow users of the admin app to see a short description of the
    297 field type via the ``django.contrib.admindocs`` application. To do this simply
    298 provide descriptive text in a ``description`` class attribute of your custom field.
    299 In the above example, the type description displayed by the ``admindocs`` application
    300 for a ``HandField`` will be 'A hand of cards (bridge style)'.
     297field type via the :ref:`django.contrib.admindocs <ref-contrib-admindocs>`
     298application. To do this simply provide descriptive text in a ``description``
     299class attribute of your custom field. In the above example, the type
     300description displayed by the ``admindocs`` application for a ``HandField`` will
     301be 'A hand of cards (bridge style)'.
    301302
    302303Useful methods
    303304--------------

  • docs/index.txt 

    diff --git a/docs/index.txt b/docs/index.txt
index aae2e27..6762bcd 100644
    a b The development process  
    161161Other batteries included
    162162========================
    163163
    164     * :ref:`Admin site <ref-contrib-admin>` | :ref:`Admin actions <ref-contrib-admin-actions>`
     164    * :ref:`Admin site <ref-contrib-admin>` | :ref:`Admin actions <ref-contrib-admin-actions>` | :ref:`Admin documentation generator<ref-contrib-admindocs>`
    165165    * :ref:`Authentication <topics-auth>`
    166166    * :ref:`Cache system <topics-cache>`
    167167    * :ref:`Conditional content processing <topics-conditional-processing>`

  • 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..466060b
    - +  
     1.. _ref-contrib-admindocs:
     2
     3========================================
     4The Django admin documentation generator
     5========================================
     6
     7.. module:: django.contrib.admindocs
     8    :synopsis: Django's admin documentation generator.
     9
     10.. currentmodule:: django.contrib.admindocs
     11
     12Django's ``admindocs`` app pulls documentation from the docstrings of models,
     13views, template tags, and template filters for any app in
     14:setting:`INSTALLED_APPS` and makes that documentation available from the
     15:mod:`Django admin <django.contrib.admin>`. You may utilize this to quickly
     16document your own code using the rich markup provided by reStructuredText.
     17
     18
     19Overview
     20========
     21
     22    * Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`.
     23    * Add ``(r'^admin/doc/', include('django.contrib.admindocs.urls'))`` to
     24      your :data:`urlpatterns`. Make sure it's included *before* the
     25      ``r'^admin/'`` entry, so that requests to ``/admin/doc/`` don't get
     26      handled by the latter entry.
     27    * Install the docutils module (http://docutils.sf.net/).
     28
     29After you've followed those steps, you can start browsing the documentation by
     30going to your admin interface and clicking the "Documentation" link in the
     31upper right of the page.
     32
     33Documentation helpers
     34=====================
     35
     36Use the following syntax when writing the docstrings in your own models, views,
     37and template tags and filters to easily create hyperlinks to other components.
     38
     39=================   =======================
     40Django Component    reStructuredText roles
     41=================   =======================
     42Models              ``:model:`appname.ModelName```
     43Views               ``:view:`appname.view_name```
     44Template tags       ``:tag:`tagname```
     45Template filters    ``:filter:`filtername```
     46Templates           ``:template:`path/to/template.html```
     47=================   =======================
     48
     49
     50Model reference
     51===============
     52
     53Because Django-powered sites usually use database objects, the **models**
     54section of the ``admindocs`` page describes each type of object in the system
     55along with all the fields and methods available on that object. Relationships
     56to other models appear as hyperlinks. Descriptions are pulled from
     57``help_text`` attributes on fields or docstrings from model methods.
     58
     59For example::
     60
     61    from django.db import models
     62
     63    class MyModel(models.Model):
     64        """
     65        Stores the URL and author of something.
     66
     67        """
     68        slug = models.SlugField(help_text="The URL of the page.")
     69        author = models.ForeignKey('auth.User')
     70
     71
     72View reference
     73==============
     74
     75Each URL in your site has a separate entry in the ``admindocs`` page and
     76clicking on an URL will show you that corresponding view. Here are a few
     77suggestions of helpful things you can document in your view docstrings:
     78
     79    * A short description of what the view does.
     80    * The **context**, or a list of variables available in the view's template.
     81    * The name of the template or templates that are used for that view.
     82
     83For example::
     84
     85    from myapp.models import MyModel
     86
     87    def my_view(request, slug):
     88        """
     89        Display an individual :model:`myapp.MyModel`.
     90
     91        **Context**
     92
     93        ``RequestContext``
     94
     95        ``mymodel``
     96            An instance of :model:`myapp.MyModel`.
     97
     98        **Template:**
     99
     100        :template:`myapp/my_template.html`
     101
     102        """
     103        return render_to_response('myapp/my_template.html', {
     104            'mymodel': MyModel.objects.get(slug=slug)
     105        }, context_instance=RequestContext(request))
     106
     107
     108Template tags and filters reference
     109===================================
     110
     111The **tags** and **filters** ``admindocs`` sections describe all the tags and
     112filters that come with Django (in fact, the :ref:`built-in tag reference
     113<ref-templates-builtins-tags>` and :ref:`built-in filter reference
     114<ref-templates-builtins-filters>` documentation come directly from those
     115pages). Any tags or filters that you create or are added by a third-party app
     116will show up here as well.
     117
     118
     119Template reference
     120==================
     121
     122There is not a place to document only templates using ``admindocs``. If you add
     123a hyperlink to a template from a view docstring, for example, the resulting
     124page will verify the given path of that template with Django’s :ref:`template
     125loaders <template-loaders>`. This can be a handy way to check if the specified
     126template exists and to show where on the filesystem that template is stored.
     127
     128
     129Included Bookmarklets
     130=====================
     131
     132Several useful bookmarklets are available from the ``admindocs`` page. They
     133require either that you are logged into an account with ``is_staff`` set, or
     134that :mod:`django.middleware.doc` is installed and you are accessing the site
     135from an IP address listed in :setting:`INTERNAL_IPS`.
     136
     137Documentation for this page
     138    Jumps you from any page to the documentation for the view that generates
     139    that page.
     140
     141Show object ID
     142    Shows the content-type and unique ID for pages that represent a single
     143    object.
     144
     145Edit this object
     146    Jumps to the admin page for pages that represent a single object.
     147
     148.. vim:filetype=rst

  • docs/ref/middleware.txt 

    diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt
index 2afd790..40bbf47 100644
    a b View metadata middleware  
    8383
    8484Sends custom ``X-View`` HTTP headers to HEAD requests that come from IP
    8585addresses defined in the :setting:`INTERNAL_IPS` setting. This is used by
    86 Django's automatic documentation system.
     86Django's :ref:`automatic documentation system <ref-contrib-admindocs>`.
    8787
    8888GZIP middleware
    8989---------------

  • docs/ref/templates/builtins.txt 

    diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 394d568..9e59b1b 100644
    a b Built-in template tags and filters  
    66
    77This document describes Django's built-in template tags and filters. It is
    88recommended that you use the :ref:`automatic documentation
    9 <template-built-in-reference>`, if available, as this will also include
     9<ref-contrib-admin-admindocs>`, if available, as this will also include
    1010documentation for any custom tags or filters installed.
    1111
    1212.. _ref-templates-builtins-tags:

  • docs/topics/templates.txt 

    diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt
index 9fa6c44..66e6d0b 100644
    a b If you use a variable that doesn't exist, the template system will insert  
    102102the value of the ``TEMPLATE_STRING_IF_INVALID`` setting, which is set to ``''``
    103103(the empty string) by default.
    104104
    105 See `Using the built-in reference`_, below, for help on finding what variables
    106 are available in a given template.
    107 
    108105Filters
    109106=======
    110107
    … … Again, these are just a few examples; see the :ref:`built-in filter reference  
    163160You can also create your own custom template filters; see
    164161:ref:`howto-custom-template-tags`.
    165162
     163.. seealso::
     164
     165    Django's admin interface can include a complete reference of all template
     166    tags and filters available for a given site, see
     167    :ref:`ref-contrib-admindocs`.
     168
    166169Tags
    167170====
    168171
    … … tag reference <ref-templates-builtins-tags>` for the complete list.  
    219222You can also create your own custom template tags; see
    220223:ref:`howto-custom-template-tags`.
    221224
     225.. seealso::
     226
     227    Django's admin interface can include a complete reference of all template
     228    tags and filters available for a given site, see
     229    :ref:`ref-contrib-admindocs`.
     230
    222231Comments
    223232========
    224233
    … … This doesn't affect what happens to data coming from the variable itself.  
    571580The variable's contents are still automatically escaped, if necessary, because
    572581they're beyond the control of the template author.
    573582
    574 .. _template-built-in-reference:
    575 
    576 Using the built-in reference
    577 ============================
    578 
    579 Django's admin interface includes a complete reference of all template tags and
    580 filters available for a given site. To activate it, follow these steps:
    581 
    582     * Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`.
    583     * Add ``(r'^admin/doc/', include('django.contrib.admindocs.urls'))`` to your
    584       :data:`urlpatterns`. Make sure it's included *before* the ``r'^admin/'``
    585       entry, so that requests to ``/admin/doc/`` don't get handled by the
    586       latter entry.
    587     * Install the docutils module (http://docutils.sf.net/).
    588 
    589 After you've followed those steps, you can start browsing the documentation by
    590 going to your admin interface and clicking the "Documentation" link in the
    591 upper right of the page.
    592 
    593 The reference is divided into 4 sections: tags, filters, models, and views.
    594 
    595 The **tags** and **filters** sections describe all the built-in tags (in fact,
    596 the tag and filter references below come directly from those pages) as well as
    597 any custom tag or filter libraries available.
    598 
    599 The **views** page is the most valuable. Each URL in your site has a separate
    600 entry here, and clicking on a URL will show you:
    601 
    602     * The name of the view function that generates that view.
    603     * A short description of what the view does.
    604     * The **context**, or a list of variables available in the view's template.
    605     * The name of the template or templates that are used for that view.
    606 
    607 Each view documentation page also has a bookmarklet that you can use to jump
    608 from any page to the documentation page for that view.
    609 
    610 Because Django-powered sites usually use database objects, the **models**
    611 section of the documentation page describes each type of object in the system
    612 along with all the fields available on that object.
    613 
    614 Taken together, the documentation pages should tell you every tag, filter,
    615 variable and object available to you in a given template.
    616 
    617583.. _loading-custom-template-libraries:
    618584
    619585Custom tag and filter libraries
Back to Top