Massive reorganization of the docs. See the new docs online at http://docs.djangoproject.com/.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8506 bcc190cf-cafb-0310-a4f2-bffc1f526a37

4 files changed, 530 insertions, 0 deletions

diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt
new file mode 100644
index 0000000000..0bf4b984c4
--- /dev/null
+++ b/docs/misc/api-stability.txt
@@ -0,0 +1,95 @@
+.. _misc-api-stability:
+
+=============
+API stability
+=============
+
+Although Django has not reached a 1.0 release, the bulk of Django's public APIs are
+stable as of the 0.95 release. This document explains which APIs will and will not
+change before the 1.0 release.
+
+What "stable" means
+===================
+
+In this context, stable means:
+
+   - All the public APIs -- everything documented in the linked documents, and
+     all methods that don't begin with an underscore -- will not be moved or
+     renamed without providing backwards-compatible aliases.
+     
+   - If new features are added to these APIs -- which is quite possible --
+     they will not break or change the meaning of existing methods. In other
+     words, "stable" does not (necessarily) mean "complete."
+     
+   - If, for some reason, an API declared stable must be removed or replaced, it
+     will be declared deprecated but will remain in the API until at least
+     version 1.1. Warnings will be issued when the deprecated method is
+     called.
+     
+   - We'll only break backwards compatibility of these APIs if a bug or
+     security hole makes it completely unavoidable.
+
+Stable APIs
+===========
+
+These APIs are stable:
+
+   - :ref:`Caching <topics-cache>`.
+   
+   - :ref:`Custom template tags and libraries <howto-custom-template-tags>`.
+     
+   - :ref:`Database lookup <topics-db-queries>` (with the exception of validation; see below).
+    
+   - :ref:`django-admin utility <ref-django-admin>`.
+   
+   - :ref:`FastCGI and mod_python integration <howto-deployment-index>`.
+   
+   - :ref:`Flatpages <ref-contrib-flatpages>`.
+   
+   - :ref:`Generic views <topics-http-generic-views>`.
+   
+   - :ref:`Internationalization <topics-i18n>`.
+   
+   - :ref:`Legacy database integration <howto-legacy-databases>`.
+   
+   - :ref:`Model definition <topics-db-models>` (with the exception of generic relations; see below).
+      
+   - :ref:`Redirects <ref-contrib-redirects>`.
+   
+   - :ref:`Request/response objects <ref-request-response>`.
+   
+   - :ref:`Sending e-mail <topics-email>`.
+   
+   - :ref:`Sessions <topics-http-sessions>`.
+   
+   - :ref:`Settings <topics-settings>`.
+   
+   - :ref:`Syndication <ref-contrib-syndication>`.
+   
+   - :ref:`Template language <topics-templates>` (with the exception of some
+     possible disambiguation of how tag arguments are passed to tags and
+     filters).
+   
+   - :ref:`Transactions <topics-db-transactions>`.
+   
+   - :ref:`URL dispatch <topics-http-urls>`.
+   
+You'll notice that this list comprises the bulk of Django's APIs. That's right
+-- most of the changes planned between now and Django 1.0 are either under the
+hood, feature additions, or changes to a few select bits. A good estimate is
+that 90% of Django can be considered forwards-compatible at this point.
+
+That said, these APIs should *not* be considered stable, and are likely to
+change:
+
+   - :ref:`Serialization <topics-serialization>` is under development; changes
+     are possible.
+
+   - Generic relations will most likely be moved out of core and into the
+     content-types contrib package to avoid core dependencies on optional
+     components.
+     
+     **New in development version**: this has now been done.
+
+   - The comments framework, which is yet undocumented, will get a complete
+     rewrite before Django 1.0.
diff --git a/docs/misc/design-philosophies.txt b/docs/misc/design-philosophies.txt
new file mode 100644
index 0000000000..43bb8096c9
--- /dev/null
+++ b/docs/misc/design-philosophies.txt
@@ -0,0 +1,316 @@
+.. _misc-design-philosophies:
+
+===================
+Design philosophies
+===================
+
+This document explains some of the fundamental philosophies Django's developers
+have used in creating the framework. Its goal is to explain the past and guide
+the future.
+
+Overall
+=======
+
+.. _loose-coupling:
+
+Loose coupling
+--------------
+
+.. index:: coupling; loose
+
+A fundamental goal of Django's stack is `loose coupling and tight cohesion`_.
+The various layers of the framework shouldn't "know" about each other unless
+absolutely necessary.
+
+For example, the template system knows nothing about Web requests, the database
+layer knows nothing about data display and the view system doesn't care which
+template system a programmer uses.
+
+Although Django comes with a full stack for convenience, the pieces of the
+stack are independent of another wherever possible.
+
+.. _`loose coupling and tight cohesion`: http://c2.com/cgi/wiki?CouplingAndCohesion
+
+.. _less-code:
+
+Less code
+---------
+
+Django apps should use as little code as possible; they should lack boilerplate.
+Django should take full advantage of Python's dynamic capabilities, such as
+introspection.
+
+.. _quick-development:
+
+Quick development
+-----------------
+
+The point of a Web framework in the 21st century is to make the tedious aspects
+of Web development fast. Django should allow for incredibly quick Web
+development.
+
+.. _dry:
+
+Don't repeat yourself (DRY)
+---------------------------
+
+.. index::
+   single: DRY
+   single: Don't repeat yourself
+
+Every distinct concept and/or piece of data should live in one, and only one,
+place. Redundancy is bad. Normalization is good.
+
+The framework, within reason, should deduce as much as possible from as little
+as possible.
+
+.. seealso::
+
+    The `discussion of DRY on the Portland Pattern Repository`__
+
+    __ http://c2.com/cgi/wiki?DontRepeatYourself
+    
+.. _explicit-is-better-than-implicit:
+
+Explicit is better than implicit
+--------------------------------
+
+This, a `core Python principle`_, means Django shouldn't do too much "magic."
+Magic shouldn't happen unless there's a really good reason for it. Magic is
+worth using only if it creates a huge convenience unattainable in other ways,
+and it isn't implemented in a way that confuses developers who are trying to
+learn how to use the feature.
+
+.. _`core Python principle`: http://www.python.org/dev/peps/pep-0020/
+
+.. _consistency:
+
+Consistency
+-----------
+
+The framework should be consistent at all levels. Consistency applies to
+everything from low-level (the Python coding style used) to high-level (the
+"experience" of using Django).
+
+Models
+======
+
+Explicit is better than implicit
+--------------------------------
+
+Fields shouldn't assume certain behaviors based solely on the name of the
+field. This requires too much knowledge of the system and is prone to errors.
+Instead, behaviors should be based on keyword arguments and, in some cases, on
+the type of the field.
+
+Include all relevant domain logic
+---------------------------------
+
+Models should encapsulate every aspect of an "object," following Martin
+Fowler's `Active Record`_ design pattern.
+
+This is why both the data represented by a model and information about
+it (its human-readable name, options like default ordering, etc.) are
+defined in the model class; all the information needed to understand a
+given model should be stored *in* the model.
+
+.. _`Active Record`: http://www.martinfowler.com/eaaCatalog/activeRecord.html
+
+Database API
+============
+
+The core goals of the database API are:
+
+SQL efficiency
+--------------
+
+It should execute SQL statements as few times as possible, and it should
+optimize statements internally.
+
+This is why developers need to call ``save()`` explicitly, rather than the
+framework saving things behind the scenes silently.
+
+This is also why the ``select_related()`` ``QuerySet`` method exists. It's an
+optional performance booster for the common case of selecting "every related
+object."
+
+Terse, powerful syntax
+----------------------
+
+The database API should allow rich, expressive statements in as little syntax
+as possible. It should not rely on importing other modules or helper objects.
+
+Joins should be performed automatically, behind the scenes, when necessary.
+
+Every object should be able to access every related object, systemwide. This
+access should work both ways.
+
+Option to drop into raw SQL easily, when needed
+-----------------------------------------------
+
+The database API should realize it's a shortcut but not necessarily an
+end-all-be-all. The framework should make it easy to write custom SQL -- entire
+statements, or just custom ``WHERE`` clauses as custom parameters to API calls.
+
+URL design
+==========
+
+Loose coupling
+--------------
+
+URLs in a Django app should not be coupled to the underlying Python code. Tying
+URLs to Python function names is a Bad And Ugly Thing.
+
+Along these lines, the Django URL system should allow URLs for the same app to
+be different in different contexts. For example, one site may put stories at
+``/stories/``, while another may use ``/news/``.
+
+Infinite flexibility
+--------------------
+
+URLs should be as flexible as possible. Any conceivable URL design should be
+allowed.
+
+Encourage best practices
+------------------------
+
+The framework should make it just as easy (or even easier) for a developer to
+design pretty URLs than ugly ones.
+
+File extensions in Web-page URLs should be avoided.
+
+Vignette-style commas in URLs deserve severe punishment.
+
+.. _definitive-urls:
+
+Definitive URLs
+---------------
+
+.. index:: urls; definitive
+
+Technically, ``foo.com/bar`` and ``foo.com/bar/`` are two different URLs, and
+search-engine robots (and some Web traffic-analyzing tools) would treat them as
+separate pages. Django should make an effort to "normalize" URLs so that
+search-engine robots don't get confused.
+
+This is the reasoning behind the :setting:`APPEND_SLASH` setting.
+
+Template system
+===============
+
+.. _separation-of-logic-and-presentation:
+
+Separate logic from presentation
+--------------------------------
+
+We see a template system as a tool that controls presentation and
+presentation-related logic -- and that's it. The template system shouldn't
+support functionality that goes beyond this basic goal.
+
+If we wanted to put everything in templates, we'd be using PHP. Been there,
+done that, wised up.
+
+Discourage redundancy
+---------------------
+
+The majority of dynamic Web sites use some sort of common sitewide design --
+a common header, footer, navigation bar, etc. The Django template system should
+make it easy to store those elements in a single place, eliminating duplicate
+code.
+
+This is the philosophy behind :ref:`template inheritance
+<template-inheritance>`.
+
+Be decoupled from HTML
+----------------------
+
+The template system shouldn't be designed so that it only outputs HTML. It
+should be equally good at generating other text-based formats, or just plain
+text.
+
+XML should not be used for template languages
+---------------------------------------------
+
+.. index:: xml; suckiness of
+
+Using an XML engine to parse templates introduces a whole new world of human
+error in editing templates -- and incurs an unacceptable level of overhead in
+template processing.
+
+Assume designer competence
+--------------------------
+
+The template system shouldn't be designed so that templates necessarily are
+displayed nicely in WYSIWYG editors such as Dreamweaver. That is too severe of
+a limitation and wouldn't allow the syntax to be as nice as it is. Django
+expects template authors are comfortable editing HTML directly.
+
+Treat whitespace obviously
+--------------------------
+
+The template system shouldn't do magic things with whitespace. If a template
+includes whitespace, the system should treat the whitespace as it treats text
+-- just display it. Any whitespace that's not in a template tag should be
+displayed.
+
+Don't invent a programming language
+-----------------------------------
+
+The template system intentionally doesn't allow the following:
+
+    * Assignment to variables
+    * Advanced logic
+
+The goal is not to invent a programming language. The goal is to offer just
+enough programming-esque functionality, such as branching and looping, that is
+essential for making presentation-related decisions.
+
+The Django template system recognizes that templates are most often written by
+*designers*, not *programmers*, and therefore should not assume Python
+knowledge.
+
+Safety and security
+-------------------
+
+The template system, out of the box, should forbid the inclusion of malicious
+code -- such as commands that delete database records.
+
+This is another reason the template system doesn't allow arbitrary Python code.
+
+Extensibility
+-------------
+
+The template system should recognize that advanced template authors may want
+to extend its technology.
+
+This is the philosophy behind custom template tags and filters.
+
+Views
+=====
+
+Simplicity
+----------
+
+Writing a view should be as simple as writing a Python function. Developers
+shouldn't have to instantiate a class when a function will do.
+
+Use request objects
+-------------------
+
+Views should have access to a request object -- an object that stores metadata
+about the current request. The object should be passed directly to a view
+function, rather than the view function having to access the request data from
+a global variable. This makes it light, clean and easy to test views by passing
+in "fake" request objects.
+
+Loose coupling
+--------------
+
+A view shouldn't care about which template system the developer uses -- or even
+whether a template system is used at all.
+
+Differentiate between GET and POST
+----------------------------------
+
+GET and POST are distinct; developers should explicitly use one or the other.
+The framework should make it easy to distinguish between GET and POST data.
diff --git a/docs/misc/distributions.txt b/docs/misc/distributions.txt
new file mode 100644
index 0000000000..c94c399ce0
--- /dev/null
+++ b/docs/misc/distributions.txt
@@ -0,0 +1,105 @@
+.. _misc-distributions:
+
+===================================
+Third-party distributions of Django
+===================================
+
+Several 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
+requires.
+
+Typically, these packages are based on the latest stable release of Django, so
+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
+=======
+
+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``.
+
+.. _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
+================
+
+If you'd like to package Django for distribution, we'd be happy to help out!
+Please join the `django-developers mailing list`_ and introduce yourself.
+
+We also encourage all distributors to subscribe to the `django-announce mailing
+list`_, which is a (very) low-traffic list for announcing new releases of Django
+and important bugfixes.
+
+.. _django-developers mailing list: http://groups.google.com/group/django-developers/
+.. _django-announce mailing list: http://groups.google.com/group/django-announce/
diff --git a/docs/misc/index.txt b/docs/misc/index.txt
new file mode 100644
index 0000000000..534171b6ed
--- /dev/null
+++ b/docs/misc/index.txt
@@ -0,0 +1,14 @@
+.. _misc-index:
+
+Meta-documentation and miscellany
+=================================
+
+Documentation that we can't find a more organized place for. Like that drawer in
+your kitchen with the scissors, batteries, duct tape, and other junk.
+
+.. toctree::
+   :maxdepth: 2
+   
+   api-stability
+   design-philosophies
+   distributions