Fixed #8996 -- Fixed small typo in documentation.txt. Thanks, rduffield
git-svn-id: http://code.djangoproject.com/svn/django/trunk@8997 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
parent
1aa8449fb7
commit
8be80c2380
|
@ -28,12 +28,12 @@ The main thing to keep in mind as you write and edit docs is that the more
|
||||||
semantic markup you can add the better. So::
|
semantic markup you can add the better. So::
|
||||||
|
|
||||||
Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
|
Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
|
||||||
|
|
||||||
Isn't nearly as helpful as::
|
Isn't nearly as helpful as::
|
||||||
|
|
||||||
Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
|
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
|
helps readers. There's basically no limit to the amount of useful markup you can
|
||||||
add.
|
add.
|
||||||
|
|
||||||
|
@ -45,39 +45,39 @@ Besides the `Sphinx built-in markup`__, Django's docs defines some extra descrip
|
||||||
__ http://sphinx.pocoo.org/markup/desc.html
|
__ http://sphinx.pocoo.org/markup/desc.html
|
||||||
|
|
||||||
* Settings::
|
* Settings::
|
||||||
|
|
||||||
.. setting:: INSTALLED_APPS
|
.. setting:: INSTALLED_APPS
|
||||||
|
|
||||||
To link to a setting, use ``:setting:`INSTALLED_APPS```.
|
To link to a setting, use ``:setting:`INSTALLED_APPS```.
|
||||||
|
|
||||||
* Template tags::
|
* Template tags::
|
||||||
|
|
||||||
.. templatetag:: regroup
|
.. templatetag:: regroup
|
||||||
|
|
||||||
To link, use ``:ttag:`regroup```.
|
To link, use ``:ttag:`regroup```.
|
||||||
|
|
||||||
* Template filters::
|
* Template filters::
|
||||||
|
|
||||||
.. templatefilter:: linebreaksbr
|
.. templatefilter:: linebreaksbr
|
||||||
|
|
||||||
To link, use ``:tfilter:`linebreaksbr```.
|
To link, use ``:tfilter:`linebreaksbr```.
|
||||||
|
|
||||||
* Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``)::
|
* Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``)::
|
||||||
|
|
||||||
.. fieldlookup:: exact
|
.. fieldlookup:: exact
|
||||||
|
|
||||||
To link, use ``:lookup:`exact```.
|
To link, use ``:lookup:`exact```.
|
||||||
|
|
||||||
* ``django-admin`` commands::
|
* ``django-admin`` commands::
|
||||||
|
|
||||||
.. django-admin:: syncdb
|
.. django-admin:: syncdb
|
||||||
|
|
||||||
To link, use ``:djadmin:`syncdb```.
|
To link, use ``:djadmin:`syncdb```.
|
||||||
|
|
||||||
* ``django-admin`` command-line options::
|
* ``django-admin`` command-line options::
|
||||||
|
|
||||||
.. django-admin-option:: --traceback
|
.. django-admin-option:: --traceback
|
||||||
|
|
||||||
To link, use ``:djadminopt:`--traceback```.
|
To link, use ``:djadminopt:`--traceback```.
|
||||||
|
|
||||||
An example
|
An example
|
||||||
|
@ -86,25 +86,25 @@ An example
|
||||||
For a quick example of how it all fits together, check this out:
|
For a quick example of how it all fits together, check this out:
|
||||||
|
|
||||||
* First, the ``ref/settings.txt`` document starts out like this::
|
* First, the ``ref/settings.txt`` document starts out like this::
|
||||||
|
|
||||||
.. _ref-settings:
|
.. _ref-settings:
|
||||||
|
|
||||||
Available settings
|
Available settings
|
||||||
==================
|
==================
|
||||||
|
|
||||||
...
|
...
|
||||||
|
|
||||||
* Next, if you look at the ``topics/settings.txt`` document, you can see how
|
* Next, if you look at the ``topics/settings.txt`` document, you can see how
|
||||||
a link to ``ref/settings`` works::
|
a link to ``ref/settings`` works::
|
||||||
|
|
||||||
Available settings
|
Available settings
|
||||||
==================
|
==================
|
||||||
|
|
||||||
For a full list of available settings, see the :ref:`settings reference
|
For a full list of available settings, see the :ref:`settings reference
|
||||||
<ref-settings>`.
|
<ref-settings>`.
|
||||||
|
|
||||||
* Next, notice how the settings (right now just the top few) are annotated::
|
* Next, notice how the settings (right now just the top few) are annotated::
|
||||||
|
|
||||||
.. setting:: ADMIN_FOR
|
.. setting:: ADMIN_FOR
|
||||||
|
|
||||||
ADMIN_FOR
|
ADMIN_FOR
|
||||||
|
@ -115,14 +115,14 @@ For a quick example of how it all fits together, check this out:
|
||||||
Used for admin-site settings modules, this should be a tuple of settings
|
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
|
modules (in the format ``'foo.bar.baz'``) for which this site is an
|
||||||
admin.
|
admin.
|
||||||
|
|
||||||
The admin site uses this in its automatically-introspected
|
The admin site uses this in its automatically-introspected
|
||||||
documentation of models, views and template tags.
|
documentation of models, views and template tags.
|
||||||
|
|
||||||
This marks up the following header as the "canonical" target for the
|
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
|
setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``, I
|
||||||
can reference it using ``:setting:`ADMIN_FOR```.
|
can reference it using ``:setting:`ADMIN_FOR```.
|
||||||
|
|
||||||
That's basically how everything fits together.
|
That's basically how everything fits together.
|
||||||
|
|
||||||
TODO
|
TODO
|
||||||
|
@ -134,45 +134,45 @@ The work is mostly done, but here's what's left, in rough order of priority.
|
||||||
this TODO item my permission and license) into
|
this TODO item my permission and license) into
|
||||||
``topics/generic-views.txt``; remove the intro material from
|
``topics/generic-views.txt``; remove the intro material from
|
||||||
``ref/generic-views.txt`` and just leave the function reference.
|
``ref/generic-views.txt`` and just leave the function reference.
|
||||||
|
|
||||||
* Change the "Added/changed in development version" callouts to proper
|
* Change the "Added/changed in development version" callouts to proper
|
||||||
Sphinx ``.. versionadded::`` or ``.. versionchanged::`` directives.
|
Sphinx ``.. versionadded::`` or ``.. versionchanged::`` directives.
|
||||||
|
|
||||||
* Check for and fix malformed links. Do this by running ``make linkcheck``
|
* Check for and fix malformed links. Do this by running ``make linkcheck``
|
||||||
and fix all of the 300+ errors/warnings.
|
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.
|
changed to proper references.
|
||||||
|
|
||||||
* Most of the various ``index.txt`` documents have *very* short or even
|
* 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
|
non-existent intro text. Each of those documents needs a good short intro
|
||||||
the content below that point.
|
the content below that point.
|
||||||
|
|
||||||
* The glossary is very perfunctory. It needs to be filled out.
|
* The glossary is very perfunctory. It needs to be filled out.
|
||||||
|
|
||||||
* Add more metadata targets: there's lots of places that look like::
|
* Add more metadata targets: there's lots of places that look like::
|
||||||
|
|
||||||
``File.close()``
|
``File.close()``
|
||||||
~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
\... these should be::
|
\... these should be::
|
||||||
|
|
||||||
.. method:: File.close()
|
.. method:: File.close()
|
||||||
|
|
||||||
That is, use metadata instead of titles.
|
That is, use metadata instead of titles.
|
||||||
|
|
||||||
* Add more links -- nearly everything that's an inline code literal
|
* 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
|
See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script
|
||||||
to help do this work.
|
to help do this work.
|
||||||
|
|
||||||
This will probably be a continuing, never-ending project.
|
This will probably be a continuing, never-ending project.
|
||||||
|
|
||||||
* Add `info field lists`__ where appropriate.
|
* Add `info field lists`__ where appropriate.
|
||||||
|
|
||||||
__ http://sphinx.pocoo.org/markup/desc.html#info-field-lists
|
__ http://sphinx.pocoo.org/markup/desc.html#info-field-lists
|
||||||
|
|
||||||
* Add ``.. code-block:: <lang>`` to literal blocks so that they get
|
* Add ``.. code-block:: <lang>`` to literal blocks so that they get
|
||||||
highlighted.
|
highlighted.
|
||||||
|
|
||||||
|
@ -189,14 +189,14 @@ Some hints for making things look/read better:
|
||||||
"crossref" directives. Others (``.. class::``, e.g.) generate their own
|
"crossref" directives. Others (``.. class::``, e.g.) generate their own
|
||||||
markup; these should go inside the section they're describing. These are
|
markup; these should go inside the section they're describing. These are
|
||||||
called "description units".
|
called "description units".
|
||||||
|
|
||||||
You can tell which are which by looking at in :file:`_ext/djangodocs.py`;
|
You can tell which are which by looking at in :file:`_ext/djangodocs.py`;
|
||||||
it registers roles as one of the other.
|
it registers roles as one of the other.
|
||||||
|
|
||||||
* When referring to classes/functions/modules, etc., you'll want to use the
|
* When referring to classes/functions/modules, etc., you'll want to use the
|
||||||
fully-qualified name of the target
|
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
|
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 ``~``
|
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
|
(that's a tilde) to get just the "last bit" of that path. So
|
||||||
|
|
Loading…
Reference in New Issue