From fa3ed6e1341f7c8b468e2267b3fafddeb58cdac2 Mon Sep 17 00:00:00 2001 From: Jeremy Dunck Date: Fri, 23 Mar 2007 16:35:57 +0000 Subject: gis: Merged revisions 4669-4785 via svnmerge from trunk. git-svn-id: http://code.djangoproject.com/svn/django/branches/gis@4786 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/add_ons.txt | 16 ++- docs/contributing.txt | 41 ++++++- docs/databases.txt | 162 +++++++++++++++++++++++++++ docs/db-api.txt | 6 +- docs/distributions.txt | 2 +- docs/django-admin.txt | 2 +- docs/fastcgi.txt | 11 ++ docs/forms.txt | 21 ++++ docs/i18n.txt | 11 ++ docs/model-api.txt | 4 + docs/release_notes_0.96.txt | 264 ++++++++++++++++++++++++++++++++++++++++++++ docs/serialization.txt | 3 +- docs/settings.txt | 10 +- docs/testing.txt | 6 + 14 files changed, 538 insertions(+), 21 deletions(-) create mode 100644 docs/databases.txt create mode 100644 docs/release_notes_0.96.txt (limited to 'docs') diff --git a/docs/add_ons.txt b/docs/add_ons.txt index 1756fe5720..8f47847e3e 100644 --- a/docs/add_ons.txt +++ b/docs/add_ons.txt @@ -1,6 +1,6 @@ -===================== -The "contrib" add-ons -===================== +============================ +The "django.contrib" add-ons +============================ Django aims to follow Python's `"batteries included" philosophy`_. It ships with a variety of extra, optional tools that solve common Web-development @@ -153,12 +153,16 @@ markup A collection of template filters that implement these common markup languages: - * Textile - * Markdown - * ReST (ReStructured Text) + * `Textile`_ + * `Markdown`_ + * `ReST (ReStructured Text)`_ For documentation, read the source code in django/contrib/markup/templatetags/markup.py. +.. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29 +.. _Markdown: http://en.wikipedia.org/wiki/Markdown +.. _ReST (ReStructured Text): http://en.wikipedia.org/wiki/ReStructuredText + redirects ========= diff --git a/docs/contributing.txt b/docs/contributing.txt index 6b2b64f672..1d2b635b76 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -195,7 +195,7 @@ The second part of this workflow involves a set of flags the describe what the ticket has or needs in order to be "ready for checkin": "Has patch" - The means the ticket has an associated patch_. These will be + This means the ticket has an associated patch_. These will be reviewed to see if the patch is "good". "Needs documentation" @@ -212,6 +212,33 @@ ticket has or needs in order to be "ready for checkin": ready for checkin. This could mean the patch no longer applies cleanly, or that the code doesn't live up to our standards. +A ticket can be resolved in a number of ways: + + "fixed" + Used by one of the core developers once a patch has been rolled into + Django and the issue is fixed. + + "invalid" + Used if the ticket is found to be incorrect or a user error. + + "wontfix" + Used when a core developer decides that this request is not + appropriate for consideration in Django. This is usually chosen after + discussion in the ``django-developers`` mailing list, and you should + feel free to join in when it's something you care about. + + "duplicate" + Used when another ticket covers the same issue. By closing duplicate + tickets, we keep all the discussion in one place, which helps everyone. + + "worksforme" + Used when the triage team is unable to replicate the original bug. + +If you believe that the ticket was closed in error -- because you're +still having the issue, or it's popped up somewhere else, or the triagers have +-- made a mistake, please reopen the ticket and tell us why. Please do not +reopen tickets that have been marked as "wontfix" by core developers. + .. _required details: `Reporting bugs`_ .. _good patch: `Patch style`_ .. _patch: `Submitting patches`_ @@ -276,9 +303,11 @@ Please follow these coding standards when writing code for inclusion in Django: def my_view(req, foo): # ... - * Please don't put your name in the code. While we appreciate all - contributions to Django, our policy is not to publish individual - developer names in code -- for instance, at the top of Python modules. + * Please don't put your name in the code you contribute. Our policy is to + keep contributors' names in the ``AUTHORS`` file distributed with Django + -- not scattered throughout the codebase itself. Feel free to include a + change to the ``AUTHORS`` file in your patch if you make more than a + single trivial change. Committing code =============== @@ -498,12 +527,12 @@ sure all other lines are commented:: # http://code.djangoproject.com/svn/django/trunk/ # /path/to/trunk - + # is a svn checkout of: # http://code.djangoproject.com/svn/django/branches// # #/path/to/ - + # On windows a path may look like this: # C:/path/to/ diff --git a/docs/databases.txt b/docs/databases.txt new file mode 100644 index 0000000000..3545b58d47 --- /dev/null +++ b/docs/databases.txt @@ -0,0 +1,162 @@ +=============================== +Notes about supported databases +=============================== + +Django attempts to support as many features as possible on all database +backends. However, not all database backends are alike, and we've had to make +design decisions on which features to support and which assumptions we can make +safely. + +This file describes some of the features that might be relevant to Django +usage. Of course, it is not intended as a replacement for server-specific +documentation or reference manuals. + +MySQL notes +=========== + +Django expects the database to support transactions, referential integrity, +and Unicode support (UTF-8 encoding). Fortunately, MySQL_ has all these +features as available as far back as 3.23. While it may be possible to use +3.23 or 4.0, you'll probably have less trouble if you use 4.1 or 5.0. + +MySQL 4.1 +--------- + +`MySQL 4.1`_ has greatly improved support for character sets. It is possible to +set different default character sets on the database, table, and column. +Previous versions have only a server-wide character set setting. It's also the +first version where the character set can be changed on the fly. 4.1 also has +support for views, but Django currently doesn't use views. + +MySQL 5.0 +--------- + +`MySQL 5.0`_ adds the ``information_schema`` database, which contains detailed +data on all database schema. Django's ``inspectdb`` feature uses this +``information_schema`` if it's available. 5.0 also has support for stored +procedures, but Django currently doesn't use stored procedures. + +.. _MySQL: http://www.mysql.com/ +.. _MySQL 4.1: http://dev.mysql.com/doc/refman/4.1/en/index.html +.. _MySQL 5.0: http://dev.mysql.com/doc/refman/5.0/en/index.html + +Storage engines +--------------- + +MySQL has several `storage engines`_ (previously called table types). You can +change the default storage engine in the server configuration. + +The default engine is MyISAM_. The main drawback of MyISAM is that it doesn't +currently support transactions or foreign keys. On the plus side, it's +currently the only engine that supports full-text indexing and searching. + +The InnoDB_ engine is fully transactional and supports foreign key references. + +The BDB_ engine, like InnoDB, is also fully transactional and supports foreign +key references. However, its use seems to be deprecated. + +`Other storage engines`_, including SolidDB_ and Falcon_, are on the horizon. +For now, InnoDB is probably your best choice. + +.. _storage engines: http://dev.mysql.com/doc/refman/5.0/en/storage-engines.html +.. _MyISAM: http://dev.mysql.com/doc/refman/5.0/en/myisam-storage-engine.html +.. _BDB: http://dev.mysql.com/doc/refman/5.0/en/bdb-storage-engine.html +.. _InnoDB: http://dev.mysql.com/doc/refman/5.0/en/innodb.html +.. _Other storage engines: http://dev.mysql.com/doc/refman/5.1/en/storage-engines-other.html +.. _SolidDB: http://forge.mysql.com/projects/view.php?id=139 +.. _Falcon: http://dev.mysql.com/doc/falcon/en/index.html + +MySQLdb +------- + +`MySQLdb`_ is the Python interface to MySQL. 1.2.1 is the first version that +has support for MySQL 4.1 and newer. If you are trying to use an older version +of MySQL, then 1.2.0 *might* work for you. + +.. _MySQLdb: http://sourceforge.net/projects/mysql-python + +Creating your database +---------------------- + +You can `create your database`_ using the command-line tools and this SQL:: + + CREATE DATABASE CHARACTER SET utf8; + +This ensures all tables and columns will use UTF-8 by default. + +.. _create your database: http://dev.mysql.com/doc/refman/5.0/en/create-database.html + +Connecting to the database +-------------------------- + +Refer to the `settings documentation`_. + +Connection settings are used in this order: + + 1. ``DATABASE_OPTIONS`` + 2. ``DATABASE_NAME``, ``DATABASE_USER``, ``DATABASE_PASSWORD``, ``DATABASE_HOST``, + ``DATABASE_PORT`` + 3. MySQL option files. + +In other words, if you set the name of the database in ``DATABASE_OPTIONS``, +this will take precedence over ``DATABASE_NAME``, which would override +anything in a `MySQL option file`_. + +Here's a sample configuration which uses a MySQL option file:: + + # settings.py + DATABASE_ENGINE = "mysql" + DATABASE_OPTIONS = { + 'read_default_file': '/path/to/my.cnf', + } + + # my.cnf + [client] + database = DATABASE_NAME + user = DATABASE_USER + passwd = DATABASE_PASSWORD + default-character-set = utf8 + +Several other MySQLdb connection options may be useful, such as ``ssl``, +``use_unicode``, ``init_command``, and ``sql_mode``. Consult the +`MySQLdb documentation`_ for more details. + +.. _settings documentation: http://www.djangoproject.com/documentation/settings/#database-engine +.. _MySQL option file: http://dev.mysql.com/doc/refman/5.0/en/option-files.html +.. _MySQLdb documentation: http://mysql-python.sourceforge.net/ + +Creating your tables +-------------------- + +When Django generates the schema, it doesn't specify a storage engine, so +tables will be created with whatever default storage engine your database +server is configured for. The easiest solution is to set your database server's +default storage engine to the desired engine. + +If you're using a hosting service and can't change your server's default +storage engine, you have a couple of options. + + * After the tables are created, execute an ``ALTER TABLE`` statement to + convert a table to a new storage engine (such as InnoDB):: + + ALTER TABLE ENGINE=INNODB; + + This can be tedious if you have a lot of tables. + + * Another option is to use the ``init_command`` option for MySQLdb prior to + creating your tables:: + + DATABASE_OPTIONS = { + # ... + "init_command": "SET storage_engine=INNODB", + # ... + } + + This sets the default storage engine upon connecting to the database. + After your tables have been created, you should remove this option. + + * Another method for changing the storage engine is described in + AlterModelOnSyncDB_. + +.. _AlterModelOnSyncDB: http://code.djangoproject.com/wiki/AlterModelOnSyncDB + diff --git a/docs/db-api.txt b/docs/db-api.txt index 20a319740e..64db3def96 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -6,7 +6,7 @@ Once you've created your `data models`_, Django automatically gives you a database-abstraction API that lets you create, retrieve, update and delete objects. This document explains that API. -.. _`data models`: http://www.djangoproject.com/documentation/model_api/ +.. _`data models`: ../model_api/ Throughout this reference, we'll refer to the following models, which comprise a weblog application:: @@ -85,7 +85,7 @@ There's no way to tell what the value of an ID will be before you call unless you explicitly specify ``primary_key=True`` on a field. See the `AutoField documentation`_.) -.. _AutoField documentation: http://www.djangoproject.com/documentation/model_api/#autofield +.. _AutoField documentation: ../model_api/#autofield Explicitly specifying auto-primary-key values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1801,4 +1801,4 @@ interface to your database. You can access your database via other tools, programming languages or database frameworks; there's nothing Django-specific about your database. -.. _Executing custom SQL: http://www.djangoproject.com/documentation/model_api/#executing-custom-sql +.. _Executing custom SQL: ../model_api/#executing-custom-sql diff --git a/docs/distributions.txt b/docs/distributions.txt index a77d3a1959..63206c535e 100644 --- a/docs/distributions.txt +++ b/docs/distributions.txt @@ -57,7 +57,7 @@ Gentoo ------ A Django build is available for `Gentoo Linux`_, and is based on Django 0.95.1. -The `current Gentoo build`_ can be installed by typing ``emerge Django``. +The `current Gentoo build`_ can be installed by typing ``emerge django``. .. _Gentoo Linux: http://www.gentoo.org/ .. _current Gentoo build: http://packages.gentoo.org/packages/?category=dev-python;name=django diff --git a/docs/django-admin.txt b/docs/django-admin.txt index 371c44e010..ef1d73cdbd 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -216,7 +216,7 @@ 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 -directories will be inluded in the search path. For example:: +directories will be included in the search path. For example:: django-admin.py loaddata foo/bar/mydata.json diff --git a/docs/fastcgi.txt b/docs/fastcgi.txt index 1efeaf09cf..5ecaac8666 100644 --- a/docs/fastcgi.txt +++ b/docs/fastcgi.txt @@ -304,3 +304,14 @@ If you have access to a command shell on a Unix system, you can accomplish this easily by using the ``touch`` command:: touch mysite.fcgi + +Serving admin media files +========================= + +Regardless of the server and configuration you eventually decide to use, you will +also need to give some thought to how to serve the admin media files. The +advice given in the modpython_ documentation is also applicable in the setups +detailed above. + +.. _modpython: ../modpython/#serving-the-admin-files + diff --git a/docs/forms.txt b/docs/forms.txt index 8c40eeb997..f76f6d27ef 100644 --- a/docs/forms.txt +++ b/docs/forms.txt @@ -417,6 +417,27 @@ Here's a simple function that might drive the above form:: form = forms.FormWrapper(manipulator, new_data, errors) return render_to_response('contact_form.html', {'form': form}) +Implementing ``flatten_data`` for custom manipulators +------------------------------------------------------ + +It is possible (although rarely needed) to replace the default automatically +created manipulators on a model with your own custom manipulators. If you do +this and you are intending to use those models in generic views, you should +also define a ``flatten_data`` method in any ``ChangeManipulator`` replacement. +This should act like the default ``flatten_data`` and return a dictionary +mapping field names to their values, like so:: + + def flatten_data(self): + obj = self.original_object + return dict( + from = obj.from, + subject = obj.subject, + ... + ) + +In this way, your new change manipulator will act exactly like the default +version. + ``FileField`` and ``ImageField`` special cases ============================================== diff --git a/docs/i18n.txt b/docs/i18n.txt index d7f5db6861..4a05e53ddf 100644 --- a/docs/i18n.txt +++ b/docs/i18n.txt @@ -282,6 +282,17 @@ How to create language files Once you've tagged your strings for later translation, you need to write (or obtain) the language translations themselves. Here's how that works. +.. admonition:: Locale restrictions + + Django does not support localizing your application into a locale for + which Django itself has not been translated. In this case, it will ignore + your translation files. If you were to try this and Django supported it, + you would inevitably see a mixture of translated strings (from your + application) and English strings (from Django itself). If you want to + support a locale for your application that is not already part of + Django, you'll need to make at least a minimal translation of the Django + core. + Message files ------------- diff --git a/docs/model-api.txt b/docs/model-api.txt index 1e7f69903d..26686b02fe 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -1216,6 +1216,10 @@ screen via ``