From 8ceeb6d8cb5933ae518b2c75338decd2fc1bc97b Mon Sep 17 00:00:00 2001 From: Boulder Sprinters Date: Mon, 9 Apr 2007 23:39:40 +0000 Subject: boulder-oracle-sprint: Merged to [4989] git-svn-id: http://code.djangoproject.com/svn/django/branches/boulder-oracle-sprint@4990 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/django-admin.txt | 75 +++++++++++++++++++++++++--------------------- docs/documentation.txt | 34 ++++++++------------- docs/legacy_databases.txt | 6 ++-- docs/model-api.txt | 6 ++-- docs/modpython.txt | 9 +++--- docs/request_response.txt | 4 +-- docs/syndication_feeds.txt | 19 +++++++++++- docs/tutorial02.txt | 4 +-- docs/url_dispatch.txt | 56 +++++++++++++++++++++------------- 9 files changed, 122 insertions(+), 91 deletions(-) (limited to 'docs') diff --git a/docs/django-admin.txt b/docs/django-admin.txt index b6028dc2a0..52ee823cc3 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -29,6 +29,9 @@ Generally, when working on a single Django project, it's easier to use ``--settings`` command line option, if you need to switch between multiple Django settings files. +The command-line examples throughout this document use ``django-admin.py`` to +be consistent, but any example can use ``manage.py`` just as well. + Usage ===== @@ -100,23 +103,24 @@ if you're ever curious to see the full list of defaults. dumpdata [appname appname ...] ------------------------------ -Output to standard output all data in the database associated with the named +Output to standard output all data in the database associated with the named application(s). By default, the database will be dumped in JSON format. If you want the output -to be in another format, use the ``--format`` option (e.g., ``format=xml``). -You may specify any Django serialization backend (including any user specified -serialization backends named in the ``SERIALIZATION_MODULES`` setting). +to be in another format, use the ``--format`` option (e.g., ``format=xml``). +You may specify any Django serialization backend (including any user specified +serialization backends named in the ``SERIALIZATION_MODULES`` setting). The +``--indent`` option can be used to pretty-print the output. If no application name is provided, all installed applications will be dumped. -The output of ``dumpdata`` can be used as input for ``loaddata``. +The output of ``dumpdata`` can be used as input for ``loaddata``. flush ----- -Return the database to the state it was in immediately after syncdb was -executed. This means that all data will be removed from the database, any +Return the database to the state it was in immediately after syncdb was +executed. This means that all data will be removed from the database, any post-synchronization handlers will be re-executed, and the ``initial_data`` fixture will be re-installed. @@ -178,37 +182,37 @@ Django will search in three locations for fixtures: 3. In the literal path named by the fixture Django will load any and all fixtures it finds in these locations that match -the provided fixture names. +the provided fixture names. -If the named fixture has a file extension, only fixtures of that type +If the named fixture has a file extension, only fixtures of that type will be loaded. For example:: django-admin.py loaddata mydata.json - -would only load JSON fixtures called ``mydata``. The fixture extension -must correspond to the registered name of a serializer (e.g., ``json`` or + +would only load JSON fixtures called ``mydata``. The fixture extension +must correspond to the registered name of a serializer (e.g., ``json`` or ``xml``). -If you omit the extension, Django will search all available fixture types +If you omit the extension, Django will search all available fixture types for a matching fixture. For example:: django-admin.py loaddata mydata - + would look for any fixture of any fixture type called ``mydata``. If a fixture directory contained ``mydata.json``, that fixture would be loaded -as a JSON fixture. However, if two fixtures with the same name but different -fixture type are discovered (for example, if ``mydata.json`` and -``mydata.xml`` were found in the same fixture directory), fixture -installation will be aborted, and any data installed in the call to +as a JSON fixture. However, if two fixtures with the same name but different +fixture type are discovered (for example, if ``mydata.json`` and +``mydata.xml`` were found in the same fixture directory), fixture +installation will be aborted, and any data installed in the call to ``loaddata`` will be removed from the database. -The fixtures that are named can include directory components. These +The fixtures that are named can include directory components. These directories will be included in the search path. For example:: django-admin.py loaddata foo/bar/mydata.json - -would search ``/fixtures/foo/bar/mydata.json`` for each installed -application, ``/foo/bar/mydata.json`` for each directory in + +would search ``/fixtures/foo/bar/mydata.json`` for each installed +application, ``/foo/bar/mydata.json`` for each directory in ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``. Note that the order in which fixture files are processed is undefined. However, @@ -217,16 +221,18 @@ one fixture can reference data in another fixture. If the database backend supports row-level constraints, these constraints will be checked at the end of the transaction. +The ``dumpdata`` command can be used to generate input for ``loaddata``. + .. admonition:: MySQL and Fixtures - Unfortunately, MySQL isn't capable of completely supporting all the + Unfortunately, MySQL isn't capable of completely supporting all the features of Django fixtures. If you use MyISAM tables, MySQL doesn't - support transactions or constraints, so you won't get a rollback if - multiple transaction files are found, or validation of fixture data. - If you use InnoDB tables, you won't be able to have any forward - references in your data files - MySQL doesn't provide a mechanism to - defer checking of row constraints until a transaction is committed. - + support transactions or constraints, so you won't get a rollback if + multiple transaction files are found, or validation of fixture data. + If you use InnoDB tables, you won't be able to have any forward + references in your data files - MySQL doesn't provide a mechanism to + defer checking of row constraints until a transaction is committed. + reset [appname appname ...] --------------------------- Executes the equivalent of ``sqlreset`` for the given appnames. @@ -366,7 +372,7 @@ Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given appnames. sqlsequencereset [appname appname ...] ---------------------------------------------- -Prints the SQL statements for resetting PostgreSQL sequences for the given +Prints the SQL statements for resetting sequences for the given appnames. See http://simon.incutio.com/archive/2004/04/21/postgres for more information. @@ -397,8 +403,8 @@ this command to install the default apps. If you're installing the ``django.contrib.auth`` application, ``syncdb`` will give you the option of creating a superuser immediately. -``syncdb`` will also search for and install any fixture named ``initial_data``. -See the documentation for ``loaddata`` for details on the specification of +``syncdb`` will also search for and install any fixture named ``initial_data``. +See the documentation for ``loaddata`` for details on the specification of fixture data files. test @@ -471,7 +477,7 @@ Example usage:: django-admin.py dumpdata --indent=4 -Specifies the number of spaces that will be used for indentation when +Specifies the number of spaces that will be used for indentation when pretty-printing output. By default, output will *not* be pretty-printed. Pretty-printing will only be enabled if the indent option is provided. @@ -512,7 +518,8 @@ and `2` is verbose output. ------------ Example usage:: - django-admin.py manage.py --adminmedia=/tmp/new-admin-style/ + + django-admin.py --adminmedia=/tmp/new-admin-style/ Tells Django where to find the various CSS and JavaScript files for the admin interface when running the development server. Normally these files are served diff --git a/docs/documentation.txt b/docs/documentation.txt index bacfb176b1..e72dd47ba1 100644 --- a/docs/documentation.txt +++ b/docs/documentation.txt @@ -42,25 +42,25 @@ On the Web The most recent version of the Django documentation lives at http://www.djangoproject.com/documentation/ . These HTML pages are generated -automatically from the text files in source control every 15 minutes. That -means they reflect the "latest and greatest" in Django -- they include the very -latest corrections and additions, and they discuss the latest Django features, +automatically from the text files in source control. That means they reflect +the "latest and greatest" in Django -- they include the very latest +corrections and additions, and they discuss the latest Django features, which may only be available to users of the Django development version. (See "Differences between versions" below.) -A key advantage of the Web-based documentation is the comment section at the -bottom of each document. This is an area for anybody to submit changes, -corrections and suggestions about the given document. The Django developers -frequently monitor the comments there and use them to improve the documentation -for everybody. +We encourage you to help improve the docs by submitting changes, corrections +and suggestions in the `ticket system`_. The Django developers actively monitor +the ticket system and use your feedback to improve the documentation for +everybody. -We encourage you to help improve the docs: it's easy! Note, however, that -comments should explicitly relate to the documentation, rather than asking -broad tech-support questions. If you need help with your particular Django -setup, try the `django-users mailing list`_ instead of posting a comment to the -documentation. +Note, however, that tickets should explicitly relate to the documentation, +rather than asking broad tech-support questions. If you need help with your +particular Django setup, try the `django-users mailing list`_ or the +`#django IRC channel`_ instead. +.. _ticket system: http://code.djangoproject.com/simpleticket?component=Documentation .. _django-users mailing list: http://groups.google.com/group/django-users +.. _#django IRC channel: irc://irc.freenode.net/django In plain text ------------- @@ -134,14 +134,6 @@ We follow this policy: frozen document that says "These docs are frozen for Django version XXX" and links to the current version of that document. - * Once a document is frozen for a Django release, we remove comments from - that page, in favor of having comments on the latest version of that - document. This is for the sake of maintainability and usability, so that - users have one, and only one, place to leave comments on a particular - document. We realize that some people may be stuck on a previous version - of Django, but we believe the usability problems with multiple versions - of a document the outweigh the benefits. - * The `main documentation Web page`_ includes links to documentation for all previous versions. diff --git a/docs/legacy_databases.txt b/docs/legacy_databases.txt index 8230c11f61..3e2753baca 100644 --- a/docs/legacy_databases.txt +++ b/docs/legacy_databases.txt @@ -39,11 +39,11 @@ Auto-generate the models Django comes with a utility that can create models by introspecting an existing database. You can view the output by running this command:: - django-admin.py inspectdb --settings=path.to.settings + python manage.py inspectdb Save this as a file by using standard Unix output redirection:: - django-admin.py inspectdb --settings=path.to.settings > models.py + python manage.py inspectdb > models.py This feature is meant as a shortcut, not as definitive model generation. See the `django-admin.py documentation`_ for more information. @@ -60,7 +60,7 @@ Install the core Django tables Next, run the ``manage.py syncdb`` command to install any extra needed database records such as admin permissions and content types:: - django-admin.py init --settings=path.to.settings + python manage.py syncdb See whether it worked ===================== diff --git a/docs/model-api.txt b/docs/model-api.txt index a03ed09eb2..400617a012 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -734,10 +734,10 @@ relationship should work. All are optional: ``limit_choices_to`` A dictionary of lookup arguments and values (see the `Database API reference`_) that limit the available admin choices for this object. Use this - with ``models.LazyDate`` to limit choices of objects - by date. For example:: + with functions from the Python ``datetime`` module + to limit choices of objects by date. For example:: - limit_choices_to = {'pub_date__lte': models.LazyDate()} + limit_choices_to = {'pub_date__lte': datetime.now} only allows the choice of related objects with a ``pub_date`` before the current date/time to be diff --git a/docs/modpython.txt b/docs/modpython.txt index 31ec1efe49..37909a09fd 100644 --- a/docs/modpython.txt +++ b/docs/modpython.txt @@ -57,17 +57,16 @@ on it, you'll need to tell mod_python:: .. caution:: - Is you are using Windows, remember that the path will contain backslashes. + If you're using Windows, remember that the path will contain backslashes. This string is passed through Python's string parser twice, so you need to escape each backslash **twice**:: PythonPath "['c:\\\\path\\\\to\\\\project'] + sys.path" - or use raw strings:: + Or, use raw strings:: PythonPath "[r'c:\\path\\to\\project'] + sys.path" - You can also add directives such as ``PythonAutoReload Off`` for performance. See the `mod_python documentation`_ for a full list of options. @@ -161,7 +160,7 @@ If, however, you have no option but to serve media files on the same Apache ``VirtualHost`` as Django, here's how you can turn off mod_python for a particular part of the site:: - + SetHandler None @@ -178,7 +177,7 @@ the ``media`` subdirectory and any URL that ends with ``.jpg``, ``.gif`` or SetEnv DJANGO_SETTINGS_MODULE mysite.settings - + SetHandler None diff --git a/docs/request_response.txt b/docs/request_response.txt index 40f06c859f..c0272461ca 100644 --- a/docs/request_response.txt +++ b/docs/request_response.txt @@ -483,8 +483,8 @@ In order to use the ``Http404`` exception to its fullest, you should create a template that is displayed when a 404 error is raised. This template should be called ``404.html`` and located in the top level of your template tree. -Customing error views ---------------------- +Customizing error views +----------------------- The 404 (page not found) view ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt index a64914de3f..2a09307e09 100644 --- a/docs/syndication_feeds.txt +++ b/docs/syndication_feeds.txt @@ -114,6 +114,9 @@ Note: `object-relational mapper`_, ``items()`` doesn't have to return model instances. Although you get a few bits of functionality "for free" by using Django models, ``items()`` can return any type of object you want. + * If you're creating an Atom feed, rather than an RSS feed, set the + ``subtitle`` attribute instead of the ``description`` attribute. See + `Publishing Atom and RSS feeds in tandem`_, later, for an example. One thing's left to do. In an RSS feed, each ```` has a ````, ``<link>`` and ``<description>``. We need to tell the framework what data to @@ -298,7 +301,7 @@ Publishing Atom and RSS feeds in tandem --------------------------------------- Some developers like to make available both Atom *and* RSS versions of their -feeds. That's easy to do with Django: Just create a subclass of your ``feed`` +feeds. That's easy to do with Django: Just create a subclass of your ``Feed`` class and set the ``feed_type`` to something different. Then update your URLconf to add the extra versions. @@ -318,6 +321,20 @@ Here's a full example:: class AtomSiteNewsFeed(RssSiteNewsFeed): feed_type = Atom1Feed + subtitle = RssSiteNewsFeed.description + +.. Note:: + In this example, the RSS feed uses a ``description`` while the Atom feed + uses a ``subtitle``. That's because Atom feeds don't provide for a + feed-level "description," but they *do* provide for a "subtitle." + + If you provide a ``description`` in your ``Feed`` class, Django will *not* + automatically put that into the ``subtitle`` element, because a subtitle + and description are not necessarily the same thing. Instead, you should + define a ``subtitle`` attribute. + + In the above example, we simply set the Atom feed's ``subtitle`` to the + RSS feed's ``description``, because it's quite short already. And the accompanying URLconf:: diff --git a/docs/tutorial02.txt b/docs/tutorial02.txt index 2eabae96f0..e9523ebfd5 100644 --- a/docs/tutorial02.txt +++ b/docs/tutorial02.txt @@ -61,8 +61,8 @@ tutorial, remember?) You should see the Django admin index page: :alt: Django admin index page :target: http://media.djangoproject.com/img/doc/tutorial/admin02.png -By default, you should see two types of editable content: groups and users. -These are core features Django ships with by default. +You should see a few other types of editable content, including groups, users +and sites. These are core features Django ships with by default. .. _"I can't log in" questions: ../faq/#the-admin-site diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt index e6e1cb6cbf..39eed0625b 100644 --- a/docs/url_dispatch.txt +++ b/docs/url_dispatch.txt @@ -192,10 +192,11 @@ The remaining arguments should be tuples in this format:: url --- -**New in development version** -The ``url()`` function can be used instead of a tuple as an argument to -``patterns()``. This is convenient if you wish to specify a name without the +**New in Django development version** + +You can use the ``url()`` function, instead of a tuple, as an argument to +``patterns()``. This is convenient if you want to specify a name without the optional extra arguments dictionary. For example:: urlpatterns = patterns('', @@ -498,26 +499,40 @@ the view prefix (as explained in "The view prefix" above) will have no effect. Naming URL patterns =================== -**New in development version** +**New in Django development version** + +It's fairly common to use the same view function in multiple URL patterns in +your URLconf. For example, these two URL patterns both point to the ``archive`` +view:: + + urlpatterns = patterns('', + (r'/archive/(\d{4})/$', archive), + (r'/archive-summary/(\d{4})/$', archive, {'summary': True}), + ) + +This is completely valid, but it leads to problems when you try to do reverse +URL matching (through the ``permalink()`` decorator or the ``{% url %}`` +template tag). Continuing this example, if you wanted to retrieve the URL for +the ``archive`` view, Django's reverse URL matcher would get confused, because +*two* URLpatterns point at that view. -It is fairly common to use the same view function in multiple URL patterns in -your URLConf. This leads to problems when you come to do reverse URL matching, -because the ``permalink()`` decorator and ``{% url %}`` template tag use the -name of the view function to find a match. +To solve this problem, Django supports **named URL patterns**. That is, you can +give a name to a URL pattern in order to distinguish it from other patterns +using the same view and parameters. Then, you can use this name in reverse URL +matching. -To solve this problem, you can give a name to each of your URL patterns in -order to distinguish them from other patterns using the same views and -parameters. You can then use this name wherever you would otherwise use the -name of the view function. For example, if you URLConf contains:: +Here's the above example, rewritten to used named URL patterns:: urlpatterns = patterns('', url(r'/archive/(\d{4})/$', archive, name="full-archive"), url(r'/archive-summary/(\d{4})/$', archive, {'summary': True}, "arch-summary"), ) -...you could refer to either the summary archive view in a template as:: +With these names in place (``full-archive`` and ``arch-summary``), you can +target each pattern individually by using its name:: {% url arch-summary 1945 %} + {% url full-archive 2007 %} Even though both URL patterns refer to the ``archive`` view here, using the ``name`` parameter to ``url()`` allows you to tell them apart in templates. @@ -527,11 +542,12 @@ not restricted to valid Python names. .. note:: - Make sure that when you name your URLs, you use names that are unlikely to - clash with any other application's choice of names. If you call your URL - pattern *comment* and another application does the same thing, there is no - guarantee which URL will be inserted into your template when you use this - name. Putting a prefix on your URL names, perhaps derived from - the application name, will decrease the chances of collision. Something - like *myapp-comment* is recommended over simply *comment*. + When you name your URL patterns, make sure you use names that are unlikely + to clash with any other application's choice of names. If you call your URL + pattern ``comment``, and another application does the same thing, there's + no guarantee which URL will be inserted into your template when you use + this name. + Putting a prefix on your URL names, perhaps derived from the application + name, will decrease the chances of collision. We recommend something like + ``myapp-comment`` instead of ``comment``. -- cgit v1.3