PageRenderTime 43ms CodeModel.GetById 16ms RepoModel.GetById 0ms app.codeStats 0ms

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

https://code.google.com/p/mango-py/
Plain Text | 161 lines | 119 code | 42 blank | 0 comment | 0 complexity | 8491cb81bf0a6c450163b89e3799b775 MD5 | raw file
Possible License(s): BSD-3-Clause
  1. ========================================
  2. The Django admin documentation generator
  3. ========================================
  4. .. module:: django.contrib.admindocs
  5. :synopsis: Django's admin documentation generator.
  6. .. currentmodule:: django.contrib.admindocs
  7. Django's :mod:`~django.contrib.admindocs` app pulls documentation from the
  8. docstrings of models, views, template tags, and template filters for any app in
  9. :setting:`INSTALLED_APPS` and makes that documentation available from the
  10. :mod:`Django admin <django.contrib.admin>`.
  11. In addition to providing offline documentation for all template tags and
  12. template filters that ship with Django, you may utilize admindocs to quickly
  13. document your own code.
  14. Overview
  15. ========
  16. To activate the :mod:`~django.contrib.admindocs`, you will need to do
  17. the following:
  18. * Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`.
  19. * Add ``(r'^admin/doc/', include('django.contrib.admindocs.urls'))`` to
  20. your :data:`urlpatterns`. Make sure it's included *before* the
  21. ``r'^admin/'`` entry, so that requests to ``/admin/doc/`` don't get
  22. handled by the latter entry.
  23. * Install the docutils Python module (http://docutils.sf.net/).
  24. * **Optional:** Linking to templates requires the :setting:`ADMIN_FOR`
  25. setting to be configured.
  26. * **Optional:** Using the admindocs bookmarklets requires the
  27. :mod:`XViewMiddleware<django.middleware.doc>` to be installed.
  28. Once those steps are complete, you can start browsing the documentation by
  29. going to your admin interface and clicking the "Documentation" link in the
  30. upper right of the page.
  31. Documentation helpers
  32. =====================
  33. The following special markup can be used in your docstrings to easily create
  34. hyperlinks to other components:
  35. ================= =======================
  36. Django Component reStructuredText roles
  37. ================= =======================
  38. Models ``:model:`appname.ModelName```
  39. Views ``:view:`appname.view_name```
  40. Template tags ``:tag:`tagname```
  41. Template filters ``:filter:`filtername```
  42. Templates ``:template:`path/to/template.html```
  43. ================= =======================
  44. Model reference
  45. ===============
  46. The **models** section of the ``admindocs`` page describes each model in the
  47. system along with all the fields and methods available on it. Relationships to
  48. other models appear as hyperlinks. Descriptions are pulled from ``help_text``
  49. attributes on fields or from docstrings on model methods.
  50. A model with useful documentation might look like this::
  51. class BlogEntry(models.Model):
  52. """
  53. Stores a single blog entry, related to :model:`blog.Blog` and
  54. :model:`auth.User`.
  55. """
  56. slug = models.SlugField(help_text="A short label, generally used in URLs.")
  57. author = models.ForeignKey(User)
  58. blog = models.ForeignKey(Blog)
  59. ...
  60. def publish(self):
  61. """Makes the blog entry live on the site."""
  62. ...
  63. View reference
  64. ==============
  65. Each URL in your site has a separate entry in the ``admindocs`` page, and
  66. clicking on a given URL will show you the corresponding view. Helpful things
  67. you can document in your view function docstrings include:
  68. * A short description of what the view does.
  69. * The **context**, or a list of variables available in the view's template.
  70. * The name of the template or templates that are used for that view.
  71. For example::
  72. from myapp.models import MyModel
  73. def my_view(request, slug):
  74. """
  75. Display an individual :model:`myapp.MyModel`.
  76. **Context**
  77. ``RequestContext``
  78. ``mymodel``
  79. An instance of :model:`myapp.MyModel`.
  80. **Template:**
  81. :template:`myapp/my_template.html`
  82. """
  83. return render_to_response('myapp/my_template.html', {
  84. 'mymodel': MyModel.objects.get(slug=slug)
  85. }, context_instance=RequestContext(request))
  86. Template tags and filters reference
  87. ===================================
  88. The **tags** and **filters** ``admindocs`` sections describe all the tags and
  89. filters that come with Django (in fact, the :ref:`built-in tag reference
  90. <ref-templates-builtins-tags>` and :ref:`built-in filter reference
  91. <ref-templates-builtins-filters>` documentation come directly from those
  92. pages). Any tags or filters that you create or are added by a third-party app
  93. will show up in these sections as well.
  94. Template reference
  95. ==================
  96. While ``admindocs`` does not include a place to document templates by
  97. themselves, if you use the ``:template:`path/to/template.html``` syntax in a
  98. docstring the resulting page will verify the path of that template with
  99. Django's :ref:`template loaders <template-loaders>`. This can be a handy way to
  100. check if the specified template exists and to show where on the filesystem that
  101. template is stored.
  102. Included Bookmarklets
  103. =====================
  104. Several useful bookmarklets are available from the ``admindocs`` page:
  105. Documentation for this page
  106. Jumps you from any page to the documentation for the view that generates
  107. that page.
  108. Show object ID
  109. Shows the content-type and unique ID for pages that represent a single
  110. object.
  111. Edit this object
  112. Jumps to the admin page for pages that represent a single object.
  113. Using these bookmarklets requires that you are either logged into the
  114. :mod:`Django admin <django.contrib.admin>` as a
  115. :class:`~django.contrib.auth.models.User` with
  116. :attr:`~django.contrib.auth.models.User.is_staff` set to `True`, or
  117. that the :mod:`django.middleware.doc` middleware and
  118. :mod:`XViewMiddleware <django.middleware.doc>` are installed and you
  119. are accessing the site from an IP address listed in :setting:`INTERNAL_IPS`.