Permalink
Browse files

Fixed a whole bunch of small docs typos, errors, and ommissions.

Fixes #8358, #8396, #8724, #9043, #9128, #9247, #9267, #9267, #9375, #9409, #9414, #9416, #9446, #9454, #9464, #9503, #9518, #9533, #9657, #9658, #9683, #9733, #9771, #9835, #9836, #9837, #9897, #9906, #9912, #9945, #9986, #9992, #10055, #10084, #10091, #10145, #10245, #10257, #10309, #10358, #10359, #10424, #10426, #10508, #10531, #10551, #10635, #10637, #10656, #10658, #10690, #10699, #19528.

Thanks to all the respective authors of those tickets.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@10371 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent d2a8bc5 commit c6c25adf6d9f71ea11f61392f6f3d221f01e5216 @jacobian jacobian committed Apr 3, 2009
Showing with 551 additions and 262 deletions.
  1. +3 −1 django/utils/html.py
  2. +3 −3 docs/_static/djangodocs.css
  3. BIN docs/_static/docicons-behindscenes.gif
  4. BIN docs/_static/docicons-behindscenes.png
  5. BIN docs/_static/docicons-note.gif
  6. BIN docs/_static/docicons-note.png
  7. BIN docs/_static/docicons-philosophy.gif
  8. BIN docs/_static/docicons-philosophy.png
  9. +5 −1 docs/howto/custom-file-storage.txt
  10. +23 −11 docs/howto/deployment/modpython.txt
  11. +1 −1 docs/howto/initial-data.txt
  12. +8 −3 docs/howto/static-files.txt
  13. +13 −4 docs/intro/tutorial01.txt
  14. +14 −2 docs/intro/tutorial03.txt
  15. +18 −8 docs/intro/tutorial04.txt
  16. +7 −74 docs/misc/distributions.txt
  17. BIN docs/obsolete/_images/formrow.gif
  18. BIN docs/obsolete/_images/formrow.png
  19. BIN docs/obsolete/_images/module.gif
  20. BIN docs/obsolete/_images/module.png
  21. BIN docs/obsolete/_images/objecttools_01.gif
  22. BIN docs/obsolete/_images/objecttools_01.png
  23. BIN docs/obsolete/_images/objecttools_02.gif
  24. BIN docs/obsolete/_images/objecttools_02.png
  25. +4 −4 docs/obsolete/admin-css.txt
  26. +38 −2 docs/ref/contrib/admin/index.txt
  27. +5 −0 docs/ref/contrib/comments/index.txt
  28. +82 −0 docs/ref/contrib/comments/models.txt
  29. +5 −0 docs/ref/contrib/flatpages.txt
  30. +7 −8 docs/ref/contrib/syndication.txt
  31. +48 −13 docs/ref/databases.txt
  32. +6 −14 docs/ref/django-admin.txt
  33. +34 −0 docs/ref/forms/api.txt
  34. +16 −49 docs/ref/forms/fields.txt
  35. +8 −1 docs/ref/forms/widgets.txt
  36. +10 −8 docs/ref/models/fields.txt
  37. +12 −0 docs/ref/models/instances.txt
  38. +24 −3 docs/ref/models/relations.txt
  39. +16 −10 docs/ref/templates/api.txt
  40. +1 −1 docs/ref/unicode.txt
  41. +14 −9 docs/releases/1.0-porting-guide.txt
  42. +26 −8 docs/topics/auth.txt
  43. +4 −4 docs/topics/cache.txt
  44. +30 −5 docs/topics/db/models.txt
  45. +6 −3 docs/topics/db/queries.txt
  46. +6 −2 docs/topics/forms/formsets.txt
  47. +35 −7 docs/topics/forms/modelforms.txt
  48. +10 −0 docs/topics/http/middleware.txt
  49. +5 −0 docs/topics/serialization.txt
  50. +4 −3 docs/topics/testing.txt
@@ -28,7 +28,9 @@
del x # Temporary variable
def escape(html):
- """Returns the given HTML with ampersands, quotes and carets encoded."""
+ """
+ Returns the given HTML with ampersands, quotes and angle brackets encoded.
+ """
return mark_safe(force_unicode(html).replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;').replace('"', '&quot;').replace("'", '&#39;'))
escape = allow_lazy(escape, unicode)
@@ -103,9 +103,9 @@ dt .literal, table .literal { background:none; }
.note, .admonition { padding:.8em 1em .8em; margin: 1em 0; border:1px solid #94da3a; }
.admonition-title { font-weight:bold; margin-top:0 !important; margin-bottom:0 !important;}
.admonition .last { margin-bottom:0 !important; }
-.note, .admonition { padding-left:65px; background:url(docicons-note.gif) .8em .8em no-repeat;}
-div.admonition-philosophy { padding-left:65px; background:url(docicons-philosophy.gif) .8em .8em no-repeat;}
-div.admonition-behind-the-scenes { padding-left:65px; background:url(docicons-behindscenes.gif) .8em .8em no-repeat;}
+.note, .admonition { padding-left:65px; background:url(docicons-note.png) .8em .8em no-repeat;}
+div.admonition-philosophy { padding-left:65px; background:url(docicons-philosophy.png) .8em .8em no-repeat;}
+div.admonition-behind-the-scenes { padding-left:65px; background:url(docicons-behindscenes.png) .8em .8em no-repeat;}
/*** versoinadded/changes ***/
div.versionadded, div.versionchanged { }
Deleted file not rendered
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Deleted file not rendered
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Deleted file not rendered
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -63,7 +63,11 @@ backend storage system.
Called by ``Storage.save()``. The ``name`` will already have gone through
``get_valid_name()`` and ``get_available_name()``, and the ``content`` will be a
-``File`` object itself. No return value is expected.
+``File`` object itself.
+
+Should return the actual name of name of the file saved (usually the ``name``
+passed in, but if the storage needs to change the file name return the new name
+instead).
``get_valid_name(name)``
------------------------
@@ -17,14 +17,22 @@ performance gains over other server arrangements.
Django requires Apache 2.x and mod_python 3.x, and you should use Apache's
`prefork MPM`_, as opposed to the `worker MPM`_.
-You may also be interested in :ref:`How to use Django with FastCGI, SCGI, or
-AJP <howto-deployment-fastcgi>`.
+.. seealso::
+
+ * Apache is a big, complex animal, and this document only scratches the
+ surface of what Apache can do. If you need more advanced information about
+ Apache, there's no better source than `Apache's own official
+ documentation`_
+
+ * You may also be interested in :ref:`How to use Django with FastCGI, SCGI,
+ or AJP <howto-deployment-fastcgi>`.
.. _Apache: http://httpd.apache.org/
.. _mod_python: http://www.modpython.org/
.. _mod_perl: http://perl.apache.org/
.. _prefork MPM: http://httpd.apache.org/docs/2.2/mod/prefork.html
.. _worker MPM: http://httpd.apache.org/docs/2.2/mod/worker.html
+.. _apache's own official documentation: http://httpd.apache.org/docs/
Basic configuration
===================
@@ -52,15 +60,15 @@ Django mod_python handler." It passes the value of :ref:`DJANGO_SETTINGS_MODULE
.. versionadded:: 1.0
The ``PythonOption django.root ...`` is new in this version.
-Because mod_python does not know we are
-serving this site from underneath the ``/mysite/`` prefix, this value needs to
-be passed through to the mod_python handler in Django, via the ``PythonOption
-django.root ...`` line. The value set on that line (the last item) should
-match the string given in the ``<Location ...>`` directive. The effect of this
-is that Django will automatically strip the ``/mysite`` string from the front
-of any URLs before matching them against your URLconf patterns. If you later
-move your site to live under ``/mysite2``, you will not have to change anything
-except the ``django.root`` option in the config file.
+Because mod_python does not know we are serving this site from underneath the
+``/mysite/`` prefix, this value needs to be passed through to the mod_python
+handler in Django, via the ``PythonOption django.root ...`` line. The value set
+on that line (the last item) should match the string given in the ``<Location
+...>`` directive. The effect of this is that Django will automatically strip the
+``/mysite`` string from the front of any URLs before matching them against your
+URLconf patterns. If you later move your site to live under ``/mysite2``, you
+will not have to change anything except the ``django.root`` option in the config
+file.
When using ``django.root`` you should make sure that what's left, after the
prefix has been removed, begins with a slash. Your URLconf patterns that are
@@ -97,6 +105,10 @@ setting the Python path for interactive usage. Whenever you try to import
something, Python will run through all the directories in ``sys.path`` in turn,
from first to last, and try to import from each directory until one succeeds.
+Make sure that your Python source files' permissions are set such that the
+Apache user (usually named ``apache`` or ``httpd`` on most systems) will have
+read access to the files.
+
An example might make this clearer. Suppose you have some applications under
``/usr/local/django-apps/`` (for example, ``/usr/local/django-apps/weblog/`` and
so forth), your settings file is at ``/var/www/mysite/settings.py`` and you have
@@ -47,7 +47,7 @@ look like in JSON:
"first_name": "Paul",
"last_name": "McCartney"
}
- },
+ }
]
And here's that same fixture as YAML:
@@ -10,9 +10,9 @@ How to serve static files
Django itself doesn't serve static (media) files, such as images, style sheets,
or video. It leaves that job to whichever Web server you choose.
-The reasoning here is that standard Web servers, such as Apache_, lighttpd_ and Cherokee_,
-are much more fine-tuned at serving static files than a Web application
-framework.
+The reasoning here is that standard Web servers, such as Apache_, lighttpd_ and
+Cherokee_, are much more fine-tuned at serving static files than a Web
+application framework.
With that said, Django does support static files **during development**. You can
use the :func:`django.views.static.serve` view to serve media files.
@@ -21,6 +21,11 @@ use the :func:`django.views.static.serve` view to serve media files.
.. _lighttpd: http://www.lighttpd.net/
.. _Cherokee: http://www.cherokee-project.com/
+.. seealso::
+
+ If you just need to serve the admin media from a nonstandard location, see
+ the :djadminopt:`--adminmedia` parameter to :djadmin:`runserver`.
+
The big, fat disclaimer
=======================
@@ -134,18 +134,27 @@ It worked!
.. admonition:: Changing the port
By default, the :djadmin:`runserver` command starts the development server
- on port 8000. If you want to change the server's port, pass it as a
- command-line argument. For instance, this command starts the server on port
- 8080:
+ on the internal IP at port 8000.
+
+ If you want to change the server's port, pass
+ it as a command-line argument. For instance, this command starts the server
+ on port 8080:
.. code-block:: bash
python manage.py runserver 8080
+
+ If you want to change the server's IP, pass it along with the port. So to
+ listen on all public IPs (useful if you want to show off your work on other
+ computers), use:
+
+ .. code-block:: bash
+
+ python manage.py runserver 0.0.0.0:8000
Full docs for the development server can be found in the
:djadmin:`runserver` reference.
-
Database setup
--------------
@@ -302,6 +302,13 @@ for a given poll. Here's the view::
The new concept here: The view raises the :exc:`~django.http.Http404` exception
if a poll with the requested ID doesn't exist.
+We'll discuss what you could put in that ``polls/detail.html`` template a bit
+later, but if you'd like to quickly get the above example working, just::
+
+ {{ poll }}
+
+will get you started for now.
+
A shortcut: get_object_or_404()
-------------------------------
@@ -357,6 +364,10 @@ in ``django/conf/urls/defaults.py``, ``handler404`` is set to
Three more things to note about 404 views:
+ * If :setting:`DEBUG` is set to ``True`` (in your settings module) then your
+ 404 view will never be used (and thus the ``404.html`` template will never
+ be rendered) because the traceback will be displayed instead.
+
* The 404 view is also called if Django doesn't find a match after checking
every regular expression in the URLconf.
@@ -365,8 +376,9 @@ Three more things to note about 404 views:
template in the root of your template directory. The default 404 view will
use that template for all 404 errors.
- * If :setting:`DEBUG` is set to ``True`` (in your settings module) then your
- 404 view will never be used, and the traceback will be displayed instead.
+ * If :setting:`DEBUG` is set to ``False`` (in your settings module) and if
+ you didn't create a ``404.html`` file, an ``Http500`` is raised instead.
+ So remember to create a ``404.html``.
Write a 500 (server error) view
===============================
@@ -20,7 +20,7 @@ tutorial, so that the template contains an HTML ``<form>`` element:
{% if error_message %}<p><strong>{{ error_message }}</strong></p>{% endif %}
- <form action="/polls/{{ poll.id }}/vote/" method="post">
+ <form action="vote/" method="post">
{% for choice in poll.choice_set.all %}
<input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}" />
<label for="choice{{ forloop.counter }}">{{ choice.choice }}</label><br />
@@ -36,12 +36,12 @@ A quick rundown:
selects one of the radio buttons and submits the form, it'll send the
POST data ``choice=3``. This is HTML Forms 101.
- * We set the form's ``action`` to ``/polls/{{ poll.id }}/vote/``, and we
- set ``method="post"``. Using ``method="post"`` (as opposed to
- ``method="get"``) is very important, because the act of submitting this
- form will alter data server-side. Whenever you create a form that alters
- data server-side, use ``method="post"``. This tip isn't specific to
- Django; it's just good Web development practice.
+ * We set the form's ``action`` to ``vote/``, and we set ``method="post"``.
+ Using ``method="post"`` (as opposed to ``method="get"``) is very
+ important, because the act of submitting this form will alter data
+ server-side. Whenever you create a form that alters data server-side, use
+ ``method="post"``. This tip isn't specific to Django; it's just good Web
+ development practice.
* ``forloop.counter`` indicates how many times the :ttag:`for` tag has gone
through its loop
@@ -170,7 +170,17 @@ to write Python code to write an app.
Let's convert our poll app to use the generic views system, so we can delete a
bunch of our own code. We'll just have to take a few steps to make the
-conversion.
+conversion. We will:
+
+ 1. Convert the URLconf.
+
+ 2. Rename a few templates.
+
+ 3. Delete some the old, now unneeded views.
+
+ 4. Fix up URL handling for the new views.
+
+Read on for details.
.. admonition:: Why the code-shuffle?
@@ -4,7 +4,7 @@
Third-party distributions of Django
===================================
-Several third-party distributors are now providing versions of Django integrated
+Many third-party distributors are now providing versions of Django integrated
with their package-management systems. These can make installation and upgrading
much easier for users of Django since the integration includes the ability to
automatically install dependencies (like database adapters) that Django
@@ -15,81 +15,14 @@ if you want to use the development version of Django you'll need to follow the
instructions for :ref:`installing the development version
<installing-development-version>` from our Subversion repository.
-FreeBSD
-=======
+If you're using Linux or a Unix installation, such as OpenSolaris,
+check with your distributor to see if they already package Django. If
+you're using a Linux distro and don't know how to find out if a package
+is available, then now is a good time to learn. The Django Wiki contains
+a list of `Third Party Distributions`_ to help you out.
-The `FreeBSD`_ ports system offers both Django 0.96 (`py-django`_) and a more
-recent, but not current, version based on Django's trunk (`py-django-devel`_).
-These are installed in the normal FreeBSD way; for Django 0.96, for example, type:
-``cd /usr/ports/www/py-django && sudo make install clean``.
+.. _`Third Party Distributions`: http://code.djangoproject.com/wiki/Distributions
-.. _FreeBSD: http://www.freebsd.org/
-.. _py-django: http://www.freebsd.org/cgi/cvsweb.cgi/ports/www/py-django/
-.. _py-django-devel: http://www.freebsd.org/cgi/cvsweb.cgi/ports/www/py-django-devel/
-
-Linux distributions
-===================
-
-Debian
-------
-
-A `packaged version of Django`_ is available for `Debian GNU/Linux`_. Version
-0.95.1 is available in the "stable" repository; Version 0.96 is available in
-the "testing" and "unstable" repositories. Regardless of your chosen repository,
-you can install Django by typing ``apt-get install python-django``.
-
-When you install this package, ``apt`` will recommend installing a database
-adapter; you should select and install the adapter for whichever database you
-plan to use with Django.
-
-.. _Debian GNU/Linux: http://www.debian.org/
-.. _packaged version of Django: http://packages.debian.org/stable/python/python-django
-
-Fedora
-------
-
-A Django package is available for `Fedora Linux`_, in the "Fedora Extras"
-repository. The `current Fedora package`_ is based on Django 0.96, and can be
-installed by typing ``yum install Django``. The previous link is for the i386
-binary. Users of other architectures should be able to use that as a starting
-point to find their preferred version.
-
-.. _Fedora Linux: http://fedora.redhat.com/
-.. _current Fedora package: http://download.fedora.redhat.com/pub/fedora/linux/extras/6/i386/repoview/Django.html
-
-Gentoo
-------
-
-A Django package is available for `Gentoo Linux`_, and is based on Django 0.96.1.
-The `current Gentoo package`_ can be installed by typing ``emerge django``.
-
-.. _Gentoo Linux: http://www.gentoo.org/
-.. _current Gentoo package: http://packages.gentoo.org/package/django
-
-Ubuntu
-------
-
-The Debian ``python-django`` package is also available for `Ubuntu Linux`_, in
-the "universe" repository for Ubuntu 7.10 ("Gutsy Gibbon"). The `current Ubuntu
-package`_ is based on Django 0.96.1 and can be installed in the same fashion as
-for Debian.
-
-.. _Ubuntu Linux: http://www.ubuntu.com/
-.. _current Ubuntu package: http://packages.ubuntu.com/gutsy/python/python-django
-
-
-Mac OS X
-========
-
-MacPorts
---------
-
-Django 0.96 can be installed via the `MacPorts`_ system. If you're using Python 2.4,
-type ``sudo port install py-django-devel``. For Python 2.5, type ``sudo port
-install py25-django-devel``. MacPorts can also be used to install a database,
-and the Python interface to your chosen database.
-
-.. _MacPorts: http://www.macports.org/
For distributors
================
Deleted file not rendered
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Deleted file not rendered
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Deleted file not rendered
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Deleted file not rendered
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -29,7 +29,7 @@ group in a box and applies certain styles to the elements within. An ``h2``
within a ``div.module`` will align to the top of the ``div`` as a header for the
whole group.
-.. image:: _images/module.gif
+.. image:: _images/module.png
:alt: Example use of module class on admin homepage
Column Types
@@ -134,7 +134,7 @@ Example from a changelist page:
<li><a href="/stories/add/" class="addlink">Add redirect</a></li>
</ul>
-.. image:: _images/objecttools_01.gif
+.. image:: _images/objecttools_01.png
:alt: Object tools on a changelist page
and from a form page:
@@ -146,7 +146,7 @@ and from a form page:
<li><a href="/r/303/152383/" class="viewsitelink">View on site</a></li>
</ul>
-.. image:: _images/objecttools_02.gif
+.. image:: _images/objecttools_02.png
:alt: Object tools on a form page
Form Styles
@@ -176,7 +176,7 @@ Each row of the form (within the ``fieldset``) should be enclosed in a ``div``
with class ``form-row``. If the field in the row is required, a class of
``required`` should also be added to the ``div.form-row``.
-.. image:: _images/formrow.gif
+.. image:: _images/formrow.png
:alt: Example use of form-row class
Labels
Oops, something went wrong. Retry.

0 comments on commit c6c25ad

Please sign in to comment.