admindocs.txt 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159
  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 ``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:** Using the admindocs bookmarklets requires
  25. ``django.contrib.admindocs.middleware.XViewMiddleware`` to be installed.
  26. Once those steps are complete, you can start browsing the documentation by
  27. going to your admin interface and clicking the "Documentation" link in the
  28. upper right of the page.
  29. Documentation helpers
  30. =====================
  31. The following special markup can be used in your docstrings to easily create
  32. hyperlinks to other components:
  33. ================= =======================
  34. Django Component reStructuredText roles
  35. ================= =======================
  36. Models ``:model:`appname.ModelName```
  37. Views ``:view:`appname.view_name```
  38. Template tags ``:tag:`tagname```
  39. Template filters ``:filter:`filtername```
  40. Templates ``:template:`path/to/template.html```
  41. ================= =======================
  42. Model reference
  43. ===============
  44. The **models** section of the ``admindocs`` page describes each model in the
  45. system along with all the fields and methods (without any arguments) available
  46. on it. While model properties don't have any arguments, they are not listed.
  47. Relationships to other models appear as hyperlinks. Descriptions are pulled
  48. from ``help_text`` attributes on fields or from docstrings on model methods.
  49. A model with useful documentation might look like this::
  50. class BlogEntry(models.Model):
  51. """
  52. Stores a single blog entry, related to :model:`blog.Blog` and
  53. :model:`auth.User`.
  54. """
  55. slug = models.SlugField(help_text="A short label, generally used in URLs.")
  56. author = models.ForeignKey(User)
  57. blog = models.ForeignKey(Blog)
  58. ...
  59. def publish(self):
  60. """Makes the blog entry live on the site."""
  61. ...
  62. View reference
  63. ==============
  64. Each URL in your site has a separate entry in the ``admindocs`` page, and
  65. clicking on a given URL will show you the corresponding view. Helpful things
  66. you can document in your view function docstrings include:
  67. * A short description of what the view does.
  68. * The **context**, or a list of variables available in the view's template.
  69. * The name of the template or templates that are used for that view.
  70. For example::
  71. from myapp.models import MyModel
  72. def my_view(request, slug):
  73. """
  74. Display an individual :model:`myapp.MyModel`.
  75. **Context**
  76. ``RequestContext``
  77. ``mymodel``
  78. An instance of :model:`myapp.MyModel`.
  79. **Template:**
  80. :template:`myapp/my_template.html`
  81. """
  82. return render_to_response('myapp/my_template.html', {
  83. 'mymodel': MyModel.objects.get(slug=slug)
  84. }, context_instance=RequestContext(request))
  85. Template tags and filters reference
  86. ===================================
  87. The **tags** and **filters** ``admindocs`` sections describe all the tags and
  88. filters that come with Django (in fact, the :ref:`built-in tag reference
  89. <ref-templates-builtins-tags>` and :ref:`built-in filter reference
  90. <ref-templates-builtins-filters>` documentation come directly from those
  91. pages). Any tags or filters that you create or are added by a third-party app
  92. will show up in these sections as well.
  93. Template reference
  94. ==================
  95. While ``admindocs`` does not include a place to document templates by
  96. themselves, if you use the ``:template:`path/to/template.html``` syntax in a
  97. docstring the resulting page will verify the path of that template with
  98. Django's :ref:`template loaders <template-loaders>`. This can be a handy way to
  99. check if the specified template exists and to show where on the filesystem that
  100. template is stored.
  101. Included Bookmarklets
  102. =====================
  103. Several useful bookmarklets are available from the ``admindocs`` page:
  104. Documentation for this page
  105. Jumps you from any page to the documentation for the view that generates
  106. that page.
  107. Show object ID
  108. Shows the content-type and unique ID for pages that represent a single
  109. object.
  110. Edit this object
  111. Jumps to the admin page for pages that represent a single object.
  112. Using these bookmarklets requires that you are either logged into the
  113. :mod:`Django admin <django.contrib.admin>` as a
  114. :class:`~django.contrib.auth.models.User` with
  115. :attr:`~django.contrib.auth.models.User.is_staff` set to ``True``, or that the
  116. ``XViewMiddleware`` is installed and you are accessing the site from an IP
  117. address listed in :setting:`INTERNAL_IPS`.