Ticket #16671: tutorial05.diff

AUTHORS

@@ -357 +357 @@
     Christian Metts
     michal@plovarna.cz
     Slawek Mikula <slawek dot mikula at gmail dot com>
+    Katie Miller <katie@sub50.com>
     Shawn Milochik <shawn@milochik.com>
     mitakummaa@gmail.com
     mmarshall
@@ -474 +475 @@
     Johan C. Stöver <johan@nilling.nl>
     Nowell Strite <http://nowell.strite.org/>
     Thomas Stromberg <tstromberg@google.com>
+    Ben Sturmfels <ben@stumbles.id.au>
     Pascal Varet
     SuperJared
     Radek Švarz <http://www.svarz.cz/translate/>

docs/intro/tutorial04.txt

@@ -322 +322 @@
 For full details on generic views, see the :doc:`generic views documentation
 </topics/http/generic-views>`.
 
-Coming soon
-===========
-
-The tutorial ends here for the time being. Future installments of the tutorial
-will cover:
-
-    * Advanced form processing
-    * Using the RSS framework
-    * Using the cache framework
-    * Using the comments framework
-    * Advanced admin features: Permissions
-    * Advanced admin features: Custom JavaScript
-
-In the meantime, you might want to check out some pointers on :doc:`where to go
-from here </intro/whatsnext>`
+When you're comfortable, read :doc:`part 5 of this tutorial
+</intro/tutorial05>` to learn about turning Polls into a reusable app.

new file docs/intro/tutorial05.txt

@@ +1 @@
+=====================================
+Writing your first Django app, part 5
+=====================================
+
+This tutorial begins where :doc:`Tutorial 4 </intro/tutorial04>` left
+off. We'll be turning our Web-poll into a stand-alone Python package.
+
+.. Draft outline:
+
+.. * motivation
+..     * what is a python package?
+..     * what is an external package?
+
+.. * preparing
+..     * moving templates into your app
+..     * parent directory
+..     * adding package boilerplate
+..     * link to packaging docs
+..     * package builder
+
+.. * using the package
+..     * where to put it
+
+.. * publishing
+..     * options for publishing
+..     * link to docs on publishing to PyPI
+
+Python packages and reusable apps
+==================================
+
+Django really is just Python. This means that you can make use of existing
+Python packages in your project. You can also take parts of your projects and
+reuse or share them.
+
+.. note::
+
+    A Python `package <http://docs.python.org/tutorial/modules.html#packages>`_
+    is a way of grouping related Python code for easy reuse. A package contains
+    one or more files of Python code (also known as "modules").
+
+    A Django *app* is nothing more than a Python package intended for use in a
+    Django project. To simplify this, an app may use common Django conventions,
+    such as having a ``models.py`` file.
+
+One of Django's most powerful features is the concept of *reusable apps*. The
+idea is that rather than rebuilding every new Django project from scratch, you
+can make use of existing packages that you, and others, have written.
+
+In fact, we're halfway there already. The Polls app we've been working on is
+already a Python package. We know this because it can be imported with ``import
+polls`` (since it contains an ``__init__.py`` file). In the previous tutorials,
+we began making Polls reusable by decoupling it from the project-level URLconf.
+
+In this tutorial, we'll take further steps to make the app easily to use in new
+projects and ready to publish for others to install and use.
+
+Completing your reusable app
+============================
+
+Currently the 
+
+Inside ``mysite/polls``, create the directory ``templates`` and *inside* that,
+the directory ``polls``. Move the ``index.html`` and ``detail.html`` templates
+into ``templates/polls``. This allows the app's templates to be distributed
+with the app. Confirm that your poll Web site still works correctly.
+
+Your project should now look like this::
+
+    mysite/
+        polls/
+            admin.py
+            templates/
+                polls/
+                    detail.html
+                    index.html
+            __init__.py
+            models.py
+            tests.py
+            urls.py
+            views.py
+        __init__.py
+        manage.py
+        settings.py
+        urls.py
+
+.. NOTE:: Why create a ``polls`` directory under templates when we're already
+   inside the Polls app? This directory is needed to avoid conflicts because of
+   how Django's ``app_directories`` template loader works.
+
+You now have a package that could be copied into new Django projects and
+immediately reused. It's not yet ready to be published though. For that, we
+need to package the app to make it easy for others to install.
+
+Packaging for external use
+==========================
+
+Python packaging isn't as hard as it sounds, especially for such a small app.
+
+    * Firstly, create a parent directory for ``polls``, outside of your Django
+      project. Call this directory ``django-polls``.
+
+    * Move the ``polls`` directory into the ``django-polls`` directory.
+
+    * Create a file ``django-polls/README.txt``::
+
+        =====
+        Polls
+        =====
+
+        Polls is a simple Django app to conduct Web-based polls. For each
+        question, visitors can choose between a fixed number of answers.
+
+    * Create a file ``django-polls/setup.py`` with the following contents::
+
+          from distutils.core import setup
+
+          setup(
+                name='django-polls',
+                version='0.1',
+                packages=['polls',],
+                long_description=open('README.txt').read(),
+                url='http://www.example.com/',
+                author='Your Name',
+                author_email='yourname@example.com',
+          )
+
+    * Try building your package with ``python setup.py sdist`` (run from inside
+      ``django-polls``. This creates a directory called ``dist`` and builds
+      your new package, ``django-polls-0.1.tar.gz``.
+
+For more information on packaging, see `The Hitchhiker's Guide to Packaging
+<http://guide.python-distribute.org/quickstart.html>`_.
+
+Using your own package
+======================
+
+Since we moved the ``polls`` directory out of the project, it's no longer
+working. We'll now fix this by installing our new ``django-polls`` package.
+
+.. NOTE:: The following steps install ``django-polls`` as a system library. In
+   general, it's best to avoid messing with your system libraries to avoid
+   breaking things. For this simple example though, the risk is low and it will
+   help with understanding packaging. We'll explain how to uninstall in
+   step 4.
+
+   For experienced users, a neater way to manage your packages is to use
+   "virtualenv" (see below).
+
+1. Inside ``django-polls/dist``, untar the new package
+   ``django-polls-0.1.tar.gz`` (e.g. ``tar xzvf django-polls-0.1.tar.gz``). If
+   you're using Windows, you can download the command-line tool bsdtar_ to do
+   this, or you can use a GUI-based tool such as 7-zip_.
+
+2. Change into the directory created in step 1 (e.g. ``cd django-polls``).
+
+3. If you're using GNU/Linux, Mac OS X or some other flavor of Unix, enter the
+   command ``sudo python setup.py install`` at the shell prompt.  If you're
+   using Windows, start up a command shell with administrator privileges and
+   run the command ``setup.py install``.
+
+   With luck, your Django project should now work correctly again. Run the
+   server again to confirm this.
+
+4. To uninstall the package, delete the directory ``polls`` and the file
+   ``django_polls-0.1.egg-info`` from your system libraries. On GNU/Linux and
+   Mac OS these files live in ``/usr/local/lib/python2.X/dist-packages``, and
+   on Windows, in ``C:\Python2X\Lib\site-packages`` (where *X* is the Python
+   minor version number). You will need administrator privileges.
+
+.. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
+.. _7-zip: http://www.7-zip.org/
+
+Publishing your app
+===================
+
+Now that we've packaged and tested ``django-polls``, it's ready to share with
+the world! If this wasn't just an example, you might now want to:
+
+    * Email the package to a friend.
+
+    * Upload the package on your Web site.
+
+    * Post the package on a public repository, such as `The Python Package
+      Index (PyPI)
+      <http://guide.python-distribute.org/contributing.html#pypi-info>`_.
+
+For more information on PyPI, see the `Quickstart
+<http://guide.python-distribute.org/quickstart.html#register-your-package-with-the-python-package-index-pypi>`_
+section of The Hitchhiker's Guide to Packaging.
+
+Installing Python packages with virtualenv
+==========================================
+
+Earlier, we installed the Polls app as a system library. This has some
+disadvantages:
+
+    * Modifying the system libraries can affect other Python software on your
+      system.
+    
+    * You won't be able to run multiple version of this package (or others with
+      the same name).
+
+Typically, these situations only arise once you're maintaining several Django
+projects. When they do, the best solution is to use `virtualenv
+<http://www.virtualenv.org/>`_. This tool allows you to maintain multiple
+isolated Python environments, each with its own copy of the libraries and
+package namespace.
+
+Further information
+===================
+
+For more on writing reusable apps, see `What is a reusable app?
+<http://ericholscher.com/projects/django-conventions/app/>`_ by Eric
+Holsher. For a collection of reusable apps to use in your own projects, see the
+`Pinax <http://pinaxproject.com/>`_ project.
+
+The tutorial ends here for the time being. In the meantime, you might want to
+check out some pointers on :doc:`where to go from here </intro/whatsnext>`.