Author: adrian
Date: 2008-09-09 23:04:57 -0500 (Tue, 09 Sep 2008)
New Revision: 8997
Modified:
django/trunk/docs/internals/documentation.txt
Log:
Fixed #8996 -- Fixed small typo in documentation.txt. Thanks, rduffield
Modified: django/trunk/docs/internals/documentation.txt
===================================================================
--- django/trunk/docs/internals/documentation.txt 2008-09-10 03:57:52 UTC
(rev 8996)
+++ django/trunk/docs/internals/documentation.txt 2008-09-10 04:04:57 UTC
(rev 8997)
@@ -28,12 +28,12 @@
semantic markup you can add the better. So::
Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
-
+
Isn't nearly as helpful as::
Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
-
-This is because Sphinx will generate proper links for the later, which greatly
+
+This is because Sphinx will generate proper links for the latter, which greatly
helps readers. There's basically no limit to the amount of useful markup you
can
add.
@@ -45,39 +45,39 @@
__ http://sphinx.pocoo.org/markup/desc.html
* Settings::
-
+
.. setting:: INSTALLED_APPS
-
+
To link to a setting, use ``:setting:`INSTALLED_APPS```.
-
+
* Template tags::
-
+
.. templatetag:: regroup
-
+
To link, use ``:ttag:`regroup```.
-
+
* Template filters::
-
+
.. templatefilter:: linebreaksbr
-
+
To link, use ``:tfilter:`linebreaksbr```.
-
+
* Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``)::
-
+
.. fieldlookup:: exact
-
+
To link, use ``:lookup:`exact```.
-
+
* ``django-admin`` commands::
-
+
.. django-admin:: syncdb
-
+
To link, use ``:djadmin:`syncdb```.
-
+
* ``django-admin`` command-line options::
-
+
.. django-admin-option:: --traceback
-
+
To link, use ``:djadminopt:`--traceback```.
An example
@@ -86,25 +86,25 @@
For a quick example of how it all fits together, check this out:
* First, the ``ref/settings.txt`` document starts out like this::
-
+
.. _ref-settings:
Available settings
==================
-
+
...
-
+
* Next, if you look at the ``topics/settings.txt`` document, you can see
how
a link to ``ref/settings`` works::
-
+
Available settings
==================
For a full list of available settings, see the :ref:`settings reference
<ref-settings>`.
-
+
* Next, notice how the settings (right now just the top few) are
annotated::
-
+
.. setting:: ADMIN_FOR
ADMIN_FOR
@@ -115,14 +115,14 @@
Used for admin-site settings modules, this should be a tuple of
settings
modules (in the format ``'foo.bar.baz'``) for which this site is an
admin.
-
+
The admin site uses this in its automatically-introspected
documentation of models, views and template tags.
-
+
This marks up the following header as the "canonical" target for the
setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``, I
can reference it using ``:setting:`ADMIN_FOR```.
-
+
That's basically how everything fits together.
TODO
@@ -134,45 +134,45 @@
this TODO item my permission and license) into
``topics/generic-views.txt``; remove the intro material from
``ref/generic-views.txt`` and just leave the function reference.
-
+
* Change the "Added/changed in development version" callouts to proper
Sphinx ``.. versionadded::`` or ``.. versionchanged::`` directives.
-
+
* Check for and fix malformed links. Do this by running ``make linkcheck``
and fix all of the 300+ errors/warnings.
-
- In particular, look at all the relative links; these need to be
+
+ In particular, look at all the relative links; these need to be
changed to proper references.
-
+
* Most of the various ``index.txt`` documents have *very* short or even
non-existent intro text. Each of those documents needs a good short intro
the content below that point.
* The glossary is very perfunctory. It needs to be filled out.
-
+
* Add more metadata targets: there's lots of places that look like::
-
+
``File.close()``
~~~~~~~~~~~~~~~~
-
+
\... these should be::
-
+
.. method:: File.close()
-
+
That is, use metadata instead of titles.
-
+
* Add more links -- nearly everything that's an inline code literal
- right now can probably be turned into a xref.
-
+ right now can probably be turned into a xref.
+
See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script
to help do this work.
This will probably be a continuing, never-ending project.
* Add `info field lists`__ where appropriate.
-
+
__ http://sphinx.pocoo.org/markup/desc.html#info-field-lists
-
+
* Add ``.. code-block:: <lang>`` to literal blocks so that they get
highlighted.
@@ -189,14 +189,14 @@
"crossref" directives. Others (``.. class::``, e.g.) generate their own
markup; these should go inside the section they're describing. These are
called "description units".
-
+
You can tell which are which by looking at in :file:`_ext/djangodocs.py`;
it registers roles as one of the other.
-
+
* When referring to classes/functions/modules, etc., you'll want to use the
fully-qualified name of the target
- (``:class:`django.contrib.contenttypes.models.ContentType```).
-
+ (``:class:`django.contrib.contenttypes.models.ContentType```).
+
Since this doesn't look all that awesome in the output -- it shows the
entire path to the object -- you can prefix the target with a ``~``
(that's a tilde) to get just the "last bit" of that path. So
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en
-~----------~----~----~----~------~----~------~--~---
