Fixed #15372 -- Switched to a startproject default layout that allows us to avoid sys.path hacks.

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

4 files changed, 142 insertions, 46 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 9e88ec489b..b438fd614e 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -246,6 +246,11 @@ these changes.
 
     * The Databrowse contrib module will be removed.
 
+    * The functions :func:`~django.core.management.setup_environ` and
+      :func:`~django.core.management.execute_manager` will be removed from
+      :mod:`django.core.management`. This also means that the old (pre-1.4)
+      style of :file:`manage.py` file will no longer work.
+
 2.0
 ---
 
diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt
index 2f2e049a16..97743dce4a 100644
--- a/docs/intro/tutorial01.txt
+++ b/docs/intro/tutorial01.txt
@@ -90,41 +90,58 @@ within your Python installation. Consider symlinking to :doc:`django-admin.py
 Let's look at what :djadmin:`startproject` created::
 
     mysite/
-        __init__.py
         manage.py
-        settings.py
-        urls.py
+        mysite/
+            __init__.py
+            settings.py
+            urls.py
+
+.. admonition:: Doesn't match what you see?
+
+    The default project layout recently changed. If you're seeing a "flat"
+    layout (with no inner :file:`mysite/` directory), you're probably using
+    a version of Django that doesn't match this tutorial version.  You'll
+    want to either switch to the older tutorial or the newer Django version.
 
 These files are:
 
-    * :file:`__init__.py`: An empty file that tells Python that this directory
-      should be considered a Python package. (Read `more about packages`_ in the
-      official Python docs if you're a Python beginner.)
+* The outer :file:`mysite/` directory is just a container for your
+  project. Its name doesn't matter to Django; you can rename it to anything
+  you like.
+
+* :file:`manage.py`: A command-line utility that lets you interact with this
+  Django project in various ways. You can read all the details about
+  :file:`manage.py` in :doc:`/ref/django-admin`.
 
-    * :file:`manage.py`: A command-line utility that lets you interact with this
-      Django project in various ways. You can read all the details about
-      :file:`manage.py` in :doc:`/ref/django-admin`.
+* The inner :file:`mysite/` directory is the actual Python package for your
+  project. Its name is the Python package name you'll need to use to import
+  anything inside it (e.g. ``import mysite.settings``).
 
-    * :file:`settings.py`: Settings/configuration for this Django project.
-      :doc:`/topics/settings` will tell you all about how settings work.
+* :file:`mysite/__init__.py`: An empty file that tells Python that this
+  directory should be considered a Python package. (Read `more about
+  packages`_ in the official Python docs if you're a Python beginner.)
 
-    * :file:`urls.py`: The URL declarations for this Django project; a "table of
-      contents" of your Django-powered site. You can read more about URLs in
-      :doc:`/topics/http/urls`.
+* :file:`mysite/settings.py`: Settings/configuration for this Django
+  project.  :doc:`/topics/settings` will tell you all about how settings
+  work.
+
+* :file:`mysite/urls.py`: The URL declarations for this Django project; a
+  "table of contents" of your Django-powered site. You can read more about
+  URLs in :doc:`/topics/http/urls`.
 
 .. _more about packages: http://docs.python.org/tutorial/modules.html#packages
 
 The development server
 ----------------------
 
-Let's verify this worked. Change into the :file:`mysite` directory, if you
-haven't already, and run the command ``python manage.py runserver``. You'll see
-the following output on the command line::
+Let's verify this worked. Change into the outer :file:`mysite` directory, if
+you haven't already, and run the command ``python manage.py runserver``. You'll
+see the following output on the command line::
 
     Validating models...
     0 errors found.
 
-    Django version 1.0, using settings 'mysite.settings'
+    Django version 1.4, using settings 'mysite.settings'
     Development server is running at http://127.0.0.1:8000/
     Quit the server with CONTROL-C.
 
@@ -168,7 +185,7 @@ It worked!
 Database setup
 --------------
 
-Now, edit :file:`settings.py`. It's a normal Python module with
+Now, edit :file:`mysite/settings.py`. It's a normal Python module with
 module-level variables representing Django settings. Change the
 following keys in the :setting:`DATABASES` ``'default'`` item to match
 your databases connection settings.
@@ -286,10 +303,11 @@ so you can focus on writing code rather than creating directories.
     multiple apps. An app can be in multiple projects.
 
 Your apps can live anywhere on your `Python path`_. In this tutorial, we'll
-create our poll app in the :file:`mysite` directory for simplicity.
+create our poll app right next to your :file:`manage.py` file so that it can be
+imported as its own top-level module, rather than a submodule of ``mysite``.
 
-To create your app, make sure you're in the :file:`mysite` directory and type
-this command:
+To create your app, make sure you're in the same directory as :file:`manage.py`
+and type this command:
 
 .. code-block:: bash
 
@@ -499,27 +517,16 @@ API Django gives you. To invoke the Python shell, use this command:
 
     python manage.py shell
 
-We're using this instead of simply typing "python", because ``manage.py`` sets
-up the project's environment for you. "Setting up the environment" involves two
-things:
-
-    * Putting ``polls`` on ``sys.path``. For flexibility, several pieces of
-      Django refer to projects in Python dotted-path notation (e.g.
-      ``'polls.models'``). In order for this to work, the ``polls``
-      package has to be on ``sys.path``.
-
-      We've already seen one example of this: the :setting:`INSTALLED_APPS`
-      setting is a list of packages in dotted-path notation.
-
-    * Setting the ``DJANGO_SETTINGS_MODULE`` environment variable, which gives
-      Django the path to your ``settings.py`` file.
+We're using this instead of simply typing "python", because :file:`manage.py`
+sets the ``DJANGO_SETTINGS_MODULE`` environment variable, which gives Django
+the Python import path to your :file:`settings.py` file.
 
 .. admonition:: Bypassing manage.py
 
-    If you'd rather not use ``manage.py``, no problem. Just make sure ``mysite``
-    and ``polls`` are at the root level on the Python path (i.e., ``import mysite``
-    and ``import polls`` work) and set the ``DJANGO_SETTINGS_MODULE`` environment
-    variable to ``mysite.settings``.
+    If you'd rather not use :file:`manage.py`, no problem. Just set the
+    ``DJANGO_SETTINGS_MODULE`` environment variable to ``mysite.settings`` and
+    run ``python`` from the same directory :file:`manage.py` is in (or ensure
+    that directory is on the Python path, so that ``import mysite`` works).
 
     For more information on all of this, see the :doc:`django-admin.py
     documentation </ref/django-admin>`.
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index c07b61c8ef..88c2569607 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -907,12 +907,6 @@ startproject <projectname>
 Creates a Django project directory structure for the given project name in the
 current directory.
 
-This command is disabled when the ``--settings`` option to
-``django-admin.py`` is used, or when the environment variable
-``DJANGO_SETTINGS_MODULE`` has been set. To re-enable it in these
-situations, either omit the ``--settings`` option or unset
-``DJANGO_SETTINGS_MODULE``.
-
 syncdb
 ------
 
diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt
index b71fd21daa..7ad403cfac 100644
--- a/docs/releases/1.4.txt
+++ b/docs/releases/1.4.txt
@@ -328,6 +328,73 @@ a :class:`~django.forms.fields.GenericIPAddressField` form field and
 the validators :data:`~django.core.validators.validate_ipv46_address` and
 :data:`~django.core.validators.validate_ipv6_address`
 
+Updated default project layout and ``manage.py``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Django 1.4 ships with an updated default project layout and ``manage.py`` file
+for the :djadmin:`startproject` management command. These fix some issues with
+the previous ``manage.py`` handling of Python import paths that caused double
+imports, trouble moving from development to deployment, and other
+difficult-to-debug path issues.
+
+The previous ``manage.py`` calls functions that are now deprecated, and thus
+projects upgrading to Django 1.4 should update their ``manage.py``. (The
+old-style ``manage.py`` will continue to work as before until Django 1.6; in
+1.5 it will raise ``DeprecationWarning``).
+
+The new recommended ``manage.py`` file should look like this::
+
+    #!/usr/bin/env python
+    import os, sys
+
+    if __name__ == "__main__":
+        os.environ.setdefault("DJANGO_SETTINGS_MODULE", "{{ project_name }}.settings")
+
+        from django.core.management import execute_from_command_line
+
+        execute_from_command_line(sys.argv)
+
+``{{ project_name }}`` should be replaced with the Python package name of the
+actual project.
+
+If settings, URLconf, and apps within the project are imported or referenced
+using the project-name prefix (e.g. ``myproject.settings``, ``ROOT_URLCONF =
+``myproject.urls``, etc), the new ``manage.py`` will need to be moved one
+directory up, so it is outside the project package rather than adjacent to
+``settings.py`` and ``urls.py``.
+
+For instance, with the following layout::
+
+    manage.py
+    mysite/
+        __init__.py
+        settings.py
+        urls.py
+        myapp/
+            __init__.py
+            models.py
+
+You could import ``mysite.settings``, ``mysite.urls``, and ``mysite.myapp``,
+but not ``settings``, ``urls``, or ``myapp`` as top-level modules.
+
+Anything imported as a top-level module can be placed adjacent to the new
+``manage.py``. For instance, to decouple "myapp" from the project module and
+import it as just ``myapp``, place it outside the ``mysite/`` directory::
+
+    manage.py
+    myapp/
+        __init__.py
+        models.py
+    mysite/
+        __init__.py
+        settings.py
+        urls.py
+
+If the same code is imported inconsistently (some places with the project
+prefix, some places without it), the imports will need to be cleaned up when
+switching to the new ``manage.py``.
+
+
 Minor features
 ~~~~~~~~~~~~~~
 
@@ -729,3 +796,26 @@ The code that powers Databrowse is licensed under the same terms as Django
 itself, and so is available to be adopted by an individual or group as
 a third-party project.
 
+``django.core.management.setup_environ``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function temporarily modified ``sys.path`` in order to make the parent
+"project" directory importable under the old flat :djadmin:`startproject`
+layout. This function is now deprecated, as its path workarounds are no longer
+needed with the new ``manage.py`` and default project layout.
+
+This function was never documented or public API, but was widely recommended
+for use in setting up a "Django environment" for a user script. These uses
+should be replaced by setting the ``DJANGO_SETTINGS_MODULE`` environment
+variable or using :func:`django.conf.settings.configure`.
+
+``django.core.management.execute_manager``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function was previously used by ``manage.py`` to execute a management
+command. It is identical to
+``django.core.management.execute_from_command_line``, except that it first
+calls ``setup_environ``, which is now deprecated. ``execute_manager`` is also
+deprecated; ``execute_from_command_line`` can be used instead. (Neither of
+these functions is documented public API, but a deprecation path is needed due
+to use in existing ``manage.py`` files.)