Ticket #16671: tutorial05.12.diff

AUTHORS

@@ -378 +378 @@
     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
     Taylor Mitchell <taylor.mitchell@gmail.com>
@@ -506 +507 @@
     Johan C. Stöver <johan@nilling.nl>
     Nowell Strite <http://nowell.strite.org/>
     Thomas Stromberg <tstromberg@google.com>
+    Ben Sturmfels <ben@sturm.com.au>
     Pascal Varet
     SuperJared
     Radek Švarz <http://www.svarz.cz/translate/>

docs/index.txt

@@ -44 +44 @@
   :doc:`Part 1 <intro/tutorial01>` |
   :doc:`Part 2 <intro/tutorial02>` |
   :doc:`Part 3 <intro/tutorial03>` |
-  :doc:`Part 4 <intro/tutorial04>`
+  :doc:`Part 4 <intro/tutorial04>` |
+  :doc:`Part 5 <intro/tutorial05>`
 
 The model layer
 ===============

docs/intro/index.txt

@@ -13 +13 @@
    tutorial02
    tutorial03
    tutorial04
+   tutorial05
    whatsnext
    
 .. seealso::
@@ -33 +34 @@
     .. _list of Python resources for non-programmers: http://wiki.python.org/moin/BeginnersGuide/NonProgrammers
     .. _dive into python: http://diveintopython.net/
     .. _dead-tree version: http://www.amazon.com/exec/obidos/ASIN/1590593561/ref=nosim/jacobian20
-    .. _books about Python: http://wiki.python.org/moin/PythonBooks
- No newline at end of file
+    .. _books about Python: http://wiki.python.org/moin/PythonBooks

docs/intro/tutorial04.txt

@@ -331 +331 @@
 For full details on generic views, see the :doc:`generic views documentation
 </topics/class-based-views/index>`.
 
-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 standalone Python package you can
+reuse in new projects and share with other people.
+
+If you haven't recently completed Tutorials 1–4, we encourage you to review
+these so that your example project matches the one described below.
+
+.. Outline:
+
+.. * motivation
+..     * what is a python package?
+..     * what is a django app?
+..     * what is a reusable app?
+
+.. * preparing
+..     * moving templates into your app
+..     * parent directory
+..     * adding package boilerplate
+..     * link to packaging docs
+..     * package builder
+
+.. * using the package
+..     * how to install
+
+.. * publishing
+..     * options for publishing
+..     * link to docs on PyPI
+
+Reusability matters
+===================
+
+It's a lot of work to design, build, test and maintain a web application. Many
+Python and Django projects share common problems. Wouldn't it be great if we
+could save some of this repeated work?
+
+Reusability is the way of life in Python. `The Python Package Index (PyPI)
+<http://guide.python-distribute.org/contributing.html#pypi-info>`_ has a vast
+range of packages you can use in your own Python programs. Django itself is
+also just a Python package. This means that you can take existing Python
+packages or Django apps and compose them into your own web project. You only
+need to write the parts that make your project unique.
+
+Let's say you were starting a new project that needed a polls app like the one
+we've been working on. How do you make this app reusable? Luckily, you're well
+on the way already. In the :doc:`Tutorial 3 </intro/tutorial03>`, we began by
+decoupling polls from the project-level URLconf. In this tutorial, we'll take
+further steps to make the app easy to use in new projects and ready to publish
+for others to install and use.
+
+.. admonition:: Package? App?
+
+    A Python `package <http://docs.python.org/tutorial/modules.html#packages>`_
+    provides 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 package can be imported with ``import foo.bar`` or ``from foo import
+    bar``. For a directory (like ``polls``) to form a package, it must contain a
+    special file ``__init__.py``, even if this file is empty.
+
+    A Django *app* is just a Python package that is specifically intended for
+    use in a Django project. An app may also use common Django conventions,
+    such as having a ``models.py`` file.
+
+    Later on we use the term *packaging* to describe the process of making a
+    Python package easy for others to install. It can be a little confusing, we
+    know.
+
+Completing your reusable app
+============================
+
+After the previous tutorials, our project should look like this::
+
+    mysite/
+        manage.py
+        mysite/
+            __init__.py
+            settings.py
+            urls.py
+            wsgi.py
+        polls/
+            admin.py
+            __init__.py
+            models.py
+            tests.py
+            urls.py
+            views.py
+
+You also have a directory somewhere called ``mytemplates`` which you created in
+:doc:`Tutorial 2 </intro/tutorial02>`. You specified its location in the
+TEMPLATE_DIRS setting. This directory should look like this::
+
+    mytemplates/
+        admin/
+            base_site.html
+        polls/
+            detail.html
+            index.html
+            results.html
+
+The polls app is already a Python package, thanks to the ``polls/__init__.py``
+file. That's a great start, but we can't just pick up this package and drop it
+into a new project. The polls templates are currently stored in the
+project-wide ``mytemplates`` directory. To make the app self-contained, it should also contain the necessary templates.
+
+Inside the ``polls`` app, create a new ``templates`` directory. Now move the
+``polls`` template directory from ``mytemplates`` into the new
+``templates``. Your project should now look like this::
+
+    mysite/
+        manage.py
+        mysite/
+            __init__.py
+            settings.py
+            urls.py
+            wsgi.py
+        polls/
+            admin.py
+            __init__.py
+            models.py
+            templates/
+                polls/
+                    detail.html
+                    index.html
+                    results.html
+            tests.py
+            urls.py
+            views.py
+
+Your project-wide templates directory should now look like this::
+
+    mytemplates/
+        admin/
+            base_site.html
+
+Looking good! Now would be a good time to confirm that your polls application
+still works correctly.
+
+The ``polls`` directory could now be copied into a new Django project and
+immediately reused. It's not quite ready to be published though. For that, we
+need to package the app to make it easy for others to install.
+
+.. admonition:: Why nested?
+
+   Why create a ``polls`` directory under ``templates`` when we're
+   already inside the polls app? This directory is needed to avoid conflicts in
+   Django's ``app_directories`` template loader.
+
+Packaging your app
+==================
+
+Python *packaging* refers to preparing your app in a specific format that can
+be easily installed and used. Django itself is packaged very much like
+this. For a small app like polls, this process isn't too difficult.
+
+1. Firstly, create a parent directory for ``polls``, outside of your Django
+   project. Call this directory ``django-polls``.
+
+2. Move the ``polls`` directory into the ``django-polls`` directory.
+
+3. Create a file ``django-polls/README.txt`` with the following contents::
+
+       =====
+       Polls
+       =====
+
+       Polls is a simple Django app to conduct Web-based polls. For each
+       question, visitors can choose between a fixed number of answers.
+
+       Detailed documentation is in the "docs" directory.
+
+       Quick start
+       -----------
+
+       1. Add "polls" to your INSTALLED_APPS setting like this::
+
+              INSTALLED_APPS = (
+                  ...
+                  'polls',
+              )
+
+       2. Include the polls URLconf in your project urls.py like this::
+
+              (r'^polls/', include('polls.urls')),
+
+       3. Run `python manage.py syncdb` to create the polls models.
+
+       4. Start the development server and visit http://127.0.0.1:8000/admin/
+          to create a poll (you'll need the Admin app enabled).
+
+       5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
+
+
+5. 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',],
+        license='',
+        long_description=open('README.txt').read(),
+        url='http://www.example.com/',
+        author='Your Name',
+        author_email='yourname@example.com',
+    )
+
+6. Only a limited set of files are included in the package by default. To also
+   include the templates, create a file ``django-polls/MANIFEST.in`` with
+   the following contents::
+
+       recursive-include polls/templates *
+
+7. It's optional, but recommended, to include detailed documentation with your
+   app. Create an empty directory ``django-polls/docs`` for future
+   documentation. Add an additional line to ``django-polls/MANIFEST.in``::
+
+       recursive-include docs *
+
+   Note that the ``docs`` directory won't be included in your package unless you
+   add some files to it.
+
+8. 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.
+
+.. admonition:: Installing as a system library
+
+   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 polls-related directories and files from
+   your system libraries. To find them, run the following at your Python prompt.
+
+   >>> import polls
+   >>> polls
+   <module 'polls' from '/usr/local/lib/python2.7/dist-packages/polls/__init__.pyc'>
+
+   In this case, we would find the polls-related files and directories in
+   ``/usr/local/lib/python2.7/dist-packages/``. Your location may be different.
+
+.. _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 could now:
+
+* 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. One detail this guide mentions
+is choosing the license under which your code is distributed.
+
+Installing Python packages with virtualenv
+==========================================
+
+Earlier, we installed the polls app as a system library. This has some
+
+* Modifying the system libraries can affect other Python software on your
+  system.
+
+* You won't be able to run multiple versions 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*. This tool
+allows you to maintain multiple isolated Python environments, each with its own
+copy of the libraries and package namespace.
+
+Learn more on the `virtualenv <http://www.virtualenv.org/>`_ Web site.
+
+More about reusable apps
+========================
+
+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>`.

new file tutorial05.diff

@@ +1 @@
+diff --git a/AUTHORS b/AUTHORS
+index 5fa9578..151e8a4 100644
+--- a/AUTHORS
++++ b/AUTHORS
+@@ -378,6 +378,7 @@ answer newbie questions, and generally made Django that much better:
+     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
+     Taylor Mitchell <taylor.mitchell@gmail.com>
+@@ -506,6 +507,7 @@ answer newbie questions, and generally made Django that much better:
+     Johan C. Stöver <johan@nilling.nl>
+     Nowell Strite <http://nowell.strite.org/>
+     Thomas Stromberg <tstromberg@google.com>
++    Ben Sturmfels <ben@sturm.com.au>
+     Pascal Varet
+     SuperJared
+     Radek Švarz <http://www.svarz.cz/translate/>
+diff --git a/docs/index.txt b/docs/index.txt
+index 3f4e303..6979979 100644
+--- a/docs/index.txt
++++ b/docs/index.txt
+@@ -44,7 +44,8 @@ Are you new to Django or to programming? This is the place to start!
+   :doc:`Part 1 <intro/tutorial01>` |
+   :doc:`Part 2 <intro/tutorial02>` |
+   :doc:`Part 3 <intro/tutorial03>` |
+-  :doc:`Part 4 <intro/tutorial04>`
++  :doc:`Part 4 <intro/tutorial04>` |
++  :doc:`Part 5 <intro/tutorial05>`
+ 
+ The model layer
+ ===============
+diff --git a/docs/intro/index.txt b/docs/intro/index.txt
+index 19290a5..186727b 100644
+--- a/docs/intro/index.txt
++++ b/docs/intro/index.txt
+@@ -13,6 +13,7 @@ place: read this material to quickly get up and running.
+    tutorial02
+    tutorial03
+    tutorial04
++   tutorial05
+    whatsnext
+    
+ .. seealso::
+@@ -33,4 +34,4 @@ place: read this material to quickly get up and running.
+     .. _list of Python resources for non-programmers: http://wiki.python.org/moin/BeginnersGuide/NonProgrammers
+     .. _dive into python: http://diveintopython.net/
+     .. _dead-tree version: http://www.amazon.com/exec/obidos/ASIN/1590593561/ref=nosim/jacobian20
+-    .. _books about Python: http://wiki.python.org/moin/PythonBooks
+\ No newline at end of file
++    .. _books about Python: http://wiki.python.org/moin/PythonBooks
+diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt
+index 49e597c..2445de4 100644
+--- a/docs/intro/tutorial04.txt
++++ b/docs/intro/tutorial04.txt
+@@ -331,18 +331,5 @@ Run the server, and use your new polling app based on generic views.
+ For full details on generic views, see the :doc:`generic views documentation
+ </topics/class-based-views/index>`.
+ 
+-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.
+diff --git a/docs/intro/tutorial05.txt b/docs/intro/tutorial05.txt
+new file mode 100644
+index 0000000..85ef56e
+--- /dev/null
++++ b/docs/intro/tutorial05.txt
+@@ -0,0 +1,324 @@
++=====================================
++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 standalone Python package you can
++reuse in new projects and share with other people.
++
++If you haven't recently completed Tutorials 1–4, we encourage you to review
++these so that your example project matches the one described below.
++
++.. Outline:
++
++.. * motivation
++..     * what is a python package?
++..     * what is a django app?
++..     * what is a reusable app?
++
++.. * preparing
++..     * moving templates into your app
++..     * parent directory
++..     * adding package boilerplate
++..     * link to packaging docs
++..     * package builder
++
++.. * using the package
++..     * how to install
++
++.. * publishing
++..     * options for publishing
++..     * link to docs on PyPI
++
++Reusability matters
++===================
++
++It's a lot of work to design, build, test and maintain a web application. Many
++Python and Django projects share common problems. Wouldn't it be great if we
++could save some of this repeated work?
++
++Reusability is the way of life in Python. `The Python Package Index (PyPI)
++<http://guide.python-distribute.org/contributing.html#pypi-info>`_ has a vast
++range of packages you can use in your own Python programs. Django itself is
++also just a Python package. This means that you can take existing Python
++packages or Django apps and compose them into your own web project. You only
++need to write the parts that make your project unique.
++
++Let's say you were starting a new project that needed a polls app like the one
++we've been working on. How do you make this app reusable? Luckily, you're well
++on the way already. In the :doc:`Tutorial 3 </intro/tutorial03>`, we began by
++decoupling polls from the project-level URLconf. In this tutorial, we'll take
++further steps to make the app easy to use in new projects and ready to publish
++for others to install and use.
++
++.. admonition:: Package? App?
++
++    A Python `package <http://docs.python.org/tutorial/modules.html#packages>`_
++    provides 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 package can be imported with ``import foo.bar`` or ``from foo import
++    bar``. For a directory (like ``polls``) to form a package, it must contain a
++    special file ``__init__.py``, even if this file is empty.
++
++    A Django *app* is just a Python package that is specifically intended for
++    use in a Django project. An app may also use common Django conventions,
++    such as having a ``models.py`` file.
++
++    Later on we use the term *packaging* to describe the process of making a
++    Python package easy for others to install. It can be a little confusing, we
++    know.
++
++Completing your reusable app
++============================
++
++After the previous tutorials, our project should look like this::
++
++    mysite/
++        manage.py
++        mysite/
++            __init__.py
++            settings.py
++            urls.py
++            wsgi.py
++        polls/
++            admin.py
++            __init__.py
++            models.py
++            tests.py
++            urls.py
++            views.py
++
++You also have a directory somewhere called ``mytemplates`` which you created in
++:doc:`Tutorial 2 </intro/tutorial02>`. You specified its location in the
++TEMPLATE_DIRS setting. This directory should look like this::
++
++    mytemplates/
++        admin/
++            base_site.html
++        polls/
++            detail.html
++            index.html
++            results.html
++
++The polls app is already a Python package, thanks to the ``polls/__init__.py``
++file. That's a great start, but we can't just pick up this package and drop it
++into a new project. The polls templates are currently stored in the
++project-wide ``mytemplates`` directory. To make the app self-contained, it should also contain the necessary templates.
++
++Inside the ``polls`` app, create a new ``templates`` directory. Now move the
++``polls`` template directory from ``mytemplates`` into the new
++``templates``. Your project should now look like this::
++
++    mysite/
++        manage.py
++        mysite/
++            __init__.py
++            settings.py
++            urls.py
++            wsgi.py
++        polls/
++            admin.py
++            __init__.py
++            models.py
++            templates/
++                polls/
++                    detail.html
++                    index.html
++                    results.html
++            tests.py
++            urls.py
++            views.py
++
++Your project-wide templates directory should now look like this::
++
++    mytemplates/
++        admin/
++            base_site.html
++
++Looking good! Now would be a good time to confirm that your polls application
++still works correctly.
++
++The ``polls`` directory could now be copied into a new Django project and
++immediately reused. It's not quite ready to be published though. For that, we
++need to package the app to make it easy for others to install.
++
++.. admonition:: Why nested?
++
++   Why create a ``polls`` directory under ``templates`` when we're
++   already inside the polls app? This directory is needed to avoid conflicts in
++   Django's ``app_directories`` template loader.
++
++Packaging your app
++==================
++
++Python *packaging* refers to preparing your app in a specific format that can
++be easily installed and used. Django itself is packaged very much like
++this. For a small app like polls, this process isn't too difficult.
++
++1. Firstly, create a parent directory for ``polls``, outside of your Django
++   project. Call this directory ``django-polls``.
++
++2. Move the ``polls`` directory into the ``django-polls`` directory.
++
++3. Create a file ``django-polls/README.txt`` with the following contents::
++
++       =====
++       Polls
++       =====
++
++       Polls is a simple Django app to conduct Web-based polls. For each
++       question, visitors can choose between a fixed number of answers.
++
++       Detailed documentation is in the "docs" directory.
++
++       Quick start
++       -----------
++
++       1. Add "polls" to your INSTALLED_APPS setting like this::
++
++              INSTALLED_APPS = (
++                  ...
++                  'polls',
++              )
++
++       2. Include the polls URLconf in your project urls.py like this::
++
++              (r'^polls/', include('polls.urls')),
++
++       3. Run `python manage.py syncdb` to create the polls models.
++
++       4. Start the development server and visit http://127.0.0.1:8000/admin/
++          to create a poll (you'll need the Admin app enabled).
++
++       5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
++
++
++5. 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',],
++       license='',
++        long_description=open('README.txt').read(),
++        url='http://www.example.com/',
++        author='Your Name',
++        author_email='yourname@example.com',
++    )
++
++6. Only a limited set of files are included in the package by default. To also
++   include the templates, create a file ``django-polls/MANIFEST.in`` with
++   the following contents::
++
++       recursive-include polls/templates *
++
++7. It's optional, but recommended, to include detailed documentation with your
++   app. Create an empty directory ``django-polls/docs`` for future
++   documentation. Add an additional line to ``django-polls/MANIFEST.in``::
++
++       recursive-include docs *
++
++   Note that the ``docs`` directory won't be included in your package unless you
++   add some files to it.
++
++8. 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.
++
++.. admonition:: Installing as a system library
++
++   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-
+ No newline at end of file