Ticket #16671: tutorial05.12.diff

File tutorial05.12.diff, 27.4 KB (added by stumbles, 8 years ago)

Note about empty docs dir and easy way to find location of installed package

  • AUTHORS

    diff --git a/AUTHORS b/AUTHORS
    index 5fa9578..151e8a4 100644
    a b answer newbie questions, and generally made Django that much better: 
    378378    Christian Metts
    379379    michal@plovarna.cz
    380380    Slawek Mikula <slawek dot mikula at gmail dot com>
     381    Katie Miller <katie@sub50.com>
    381382    Shawn Milochik <shawn@milochik.com>
    382383    mitakummaa@gmail.com
    383384    Taylor Mitchell <taylor.mitchell@gmail.com>
    answer newbie questions, and generally made Django that much better: 
    506507    Johan C. Stöver <johan@nilling.nl>
    507508    Nowell Strite <http://nowell.strite.org/>
    508509    Thomas Stromberg <tstromberg@google.com>
     510    Ben Sturmfels <ben@sturm.com.au>
    509511    Pascal Varet
    510512    SuperJared
    511513    Radek Švarz <http://www.svarz.cz/translate/>
  • docs/index.txt

    diff --git a/docs/index.txt b/docs/index.txt
    index 3f4e303..6979979 100644
    a b Are you new to Django or to programming? This is the place to start! 
    4444  :doc:`Part 1 <intro/tutorial01>` |
    4545  :doc:`Part 2 <intro/tutorial02>` |
    4646  :doc:`Part 3 <intro/tutorial03>` |
    47   :doc:`Part 4 <intro/tutorial04>`
     47  :doc:`Part 4 <intro/tutorial04>` |
     48  :doc:`Part 5 <intro/tutorial05>`
    4849
    4950The model layer
    5051===============
  • docs/intro/index.txt

    diff --git a/docs/intro/index.txt b/docs/intro/index.txt
    index 19290a5..186727b 100644
    a b place: read this material to quickly get up and running. 
    1313   tutorial02
    1414   tutorial03
    1515   tutorial04
     16   tutorial05
    1617   whatsnext
    1718   
    1819.. seealso::
    place: read this material to quickly get up and running. 
    3334    .. _list of Python resources for non-programmers: http://wiki.python.org/moin/BeginnersGuide/NonProgrammers
    3435    .. _dive into python: http://diveintopython.net/
    3536    .. _dead-tree version: http://www.amazon.com/exec/obidos/ASIN/1590593561/ref=nosim/jacobian20
    36     .. _books about Python: http://wiki.python.org/moin/PythonBooks
    37  No newline at end of file
     37    .. _books about Python: http://wiki.python.org/moin/PythonBooks
  • docs/intro/tutorial04.txt

    diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt
    index 49e597c..2445de4 100644
    a b Run the server, and use your new polling app based on generic views. 
    331331For full details on generic views, see the :doc:`generic views documentation
    332332</topics/class-based-views/index>`.
    333333
    334 Coming soon
    335 ===========
    336 
    337 The tutorial ends here for the time being. Future installments of the tutorial
    338 will cover:
    339 
    340 * Advanced form processing
    341 * Using the RSS framework
    342 * Using the cache framework
    343 * Using the comments framework
    344 * Advanced admin features: Permissions
    345 * Advanced admin features: Custom JavaScript
    346 
    347 In the meantime, you might want to check out some pointers on :doc:`where to go
    348 from here </intro/whatsnext>`
     334When you're comfortable, read :doc:`part 5 of this tutorial
     335</intro/tutorial05>` to learn about turning Polls into a reusable app.
  • new file docs/intro/tutorial05.txt

    diff --git a/docs/intro/tutorial05.txt b/docs/intro/tutorial05.txt
    new file mode 100644
    index 0000000..85ef56e
    - +  
     1=====================================
     2Writing your first Django app, part 5
     3=====================================
     4
     5This tutorial begins where :doc:`Tutorial 4 </intro/tutorial04>` left
     6off. We'll be turning our Web-poll into a standalone Python package you can
     7reuse in new projects and share with other people.
     8
     9If you haven't recently completed Tutorials 1–4, we encourage you to review
     10these so that your example project matches the one described below.
     11
     12.. Outline:
     13
     14.. * motivation
     15..     * what is a python package?
     16..     * what is a django app?
     17..     * what is a reusable app?
     18
     19.. * preparing
     20..     * moving templates into your app
     21..     * parent directory
     22..     * adding package boilerplate
     23..     * link to packaging docs
     24..     * package builder
     25
     26.. * using the package
     27..     * how to install
     28
     29.. * publishing
     30..     * options for publishing
     31..     * link to docs on PyPI
     32
     33Reusability matters
     34===================
     35
     36It's a lot of work to design, build, test and maintain a web application. Many
     37Python and Django projects share common problems. Wouldn't it be great if we
     38could save some of this repeated work?
     39
     40Reusability is the way of life in Python. `The Python Package Index (PyPI)
     41<http://guide.python-distribute.org/contributing.html#pypi-info>`_ has a vast
     42range of packages you can use in your own Python programs. Django itself is
     43also just a Python package. This means that you can take existing Python
     44packages or Django apps and compose them into your own web project. You only
     45need to write the parts that make your project unique.
     46
     47Let's say you were starting a new project that needed a polls app like the one
     48we've been working on. How do you make this app reusable? Luckily, you're well
     49on the way already. In the :doc:`Tutorial 3 </intro/tutorial03>`, we began by
     50decoupling polls from the project-level URLconf. In this tutorial, we'll take
     51further steps to make the app easy to use in new projects and ready to publish
     52for others to install and use.
     53
     54.. admonition:: Package? App?
     55
     56    A Python `package <http://docs.python.org/tutorial/modules.html#packages>`_
     57    provides a way of grouping related Python code for easy reuse. A package contains
     58    one or more files of Python code (also known as "modules").
     59
     60    A package can be imported with ``import foo.bar`` or ``from foo import
     61    bar``. For a directory (like ``polls``) to form a package, it must contain a
     62    special file ``__init__.py``, even if this file is empty.
     63
     64    A Django *app* is just a Python package that is specifically intended for
     65    use in a Django project. An app may also use common Django conventions,
     66    such as having a ``models.py`` file.
     67
     68    Later on we use the term *packaging* to describe the process of making a
     69    Python package easy for others to install. It can be a little confusing, we
     70    know.
     71
     72Completing your reusable app
     73============================
     74
     75After the previous tutorials, our project should look like this::
     76
     77    mysite/
     78        manage.py
     79        mysite/
     80            __init__.py
     81            settings.py
     82            urls.py
     83            wsgi.py
     84        polls/
     85            admin.py
     86            __init__.py
     87            models.py
     88            tests.py
     89            urls.py
     90            views.py
     91
     92You also have a directory somewhere called ``mytemplates`` which you created in
     93:doc:`Tutorial 2 </intro/tutorial02>`. You specified its location in the
     94TEMPLATE_DIRS setting. This directory should look like this::
     95
     96    mytemplates/
     97        admin/
     98            base_site.html
     99        polls/
     100            detail.html
     101            index.html
     102            results.html
     103
     104The polls app is already a Python package, thanks to the ``polls/__init__.py``
     105file. That's a great start, but we can't just pick up this package and drop it
     106into a new project. The polls templates are currently stored in the
     107project-wide ``mytemplates`` directory. To make the app self-contained, it should also contain the necessary templates.
     108
     109Inside the ``polls`` app, create a new ``templates`` directory. Now move the
     110``polls`` template directory from ``mytemplates`` into the new
     111``templates``. Your project should now look like this::
     112
     113    mysite/
     114        manage.py
     115        mysite/
     116            __init__.py
     117            settings.py
     118            urls.py
     119            wsgi.py
     120        polls/
     121            admin.py
     122            __init__.py
     123            models.py
     124            templates/
     125                polls/
     126                    detail.html
     127                    index.html
     128                    results.html
     129            tests.py
     130            urls.py
     131            views.py
     132
     133Your project-wide templates directory should now look like this::
     134
     135    mytemplates/
     136        admin/
     137            base_site.html
     138
     139Looking good! Now would be a good time to confirm that your polls application
     140still works correctly.
     141
     142The ``polls`` directory could now be copied into a new Django project and
     143immediately reused. It's not quite ready to be published though. For that, we
     144need to package the app to make it easy for others to install.
     145
     146.. admonition:: Why nested?
     147
     148   Why create a ``polls`` directory under ``templates`` when we're
     149   already inside the polls app? This directory is needed to avoid conflicts in
     150   Django's ``app_directories`` template loader.
     151
     152Packaging your app
     153==================
     154
     155Python *packaging* refers to preparing your app in a specific format that can
     156be easily installed and used. Django itself is packaged very much like
     157this. For a small app like polls, this process isn't too difficult.
     158
     1591. Firstly, create a parent directory for ``polls``, outside of your Django
     160   project. Call this directory ``django-polls``.
     161
     1622. Move the ``polls`` directory into the ``django-polls`` directory.
     163
     1643. Create a file ``django-polls/README.txt`` with the following contents::
     165
     166       =====
     167       Polls
     168       =====
     169
     170       Polls is a simple Django app to conduct Web-based polls. For each
     171       question, visitors can choose between a fixed number of answers.
     172
     173       Detailed documentation is in the "docs" directory.
     174
     175       Quick start
     176       -----------
     177
     178       1. Add "polls" to your INSTALLED_APPS setting like this::
     179
     180              INSTALLED_APPS = (
     181                  ...
     182                  'polls',
     183              )
     184
     185       2. Include the polls URLconf in your project urls.py like this::
     186
     187              (r'^polls/', include('polls.urls')),
     188
     189       3. Run `python manage.py syncdb` to create the polls models.
     190
     191       4. Start the development server and visit http://127.0.0.1:8000/admin/
     192          to create a poll (you'll need the Admin app enabled).
     193
     194       5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
     195
     196
     1975. Create a file ``django-polls/setup.py`` with the following contents::
     198
     199    from distutils.core import setup
     200
     201    setup(
     202        name='django-polls',
     203        version='0.1',
     204        packages=['polls',],
     205        license='',
     206        long_description=open('README.txt').read(),
     207        url='http://www.example.com/',
     208        author='Your Name',
     209        author_email='yourname@example.com',
     210    )
     211
     2126. Only a limited set of files are included in the package by default. To also
     213   include the templates, create a file ``django-polls/MANIFEST.in`` with
     214   the following contents::
     215
     216       recursive-include polls/templates *
     217
     2187. It's optional, but recommended, to include detailed documentation with your
     219   app. Create an empty directory ``django-polls/docs`` for future
     220   documentation. Add an additional line to ``django-polls/MANIFEST.in``::
     221
     222       recursive-include docs *
     223
     224   Note that the ``docs`` directory won't be included in your package unless you
     225   add some files to it.
     226
     2278. Try building your package with ``python setup.py sdist`` (run from inside
     228   ``django-polls``). This creates a directory called ``dist`` and builds your
     229   new package, ``django-polls-0.1.tar.gz``.
     230
     231For more information on packaging, see `The Hitchhiker's Guide to Packaging
     232<http://guide.python-distribute.org/quickstart.html>`_.
     233
     234Using your own package
     235======================
     236
     237Since we moved the ``polls`` directory out of the project, it's no longer
     238working. We'll now fix this by installing our new ``django-polls`` package.
     239
     240.. admonition:: Installing as a system library
     241
     242   The following steps install ``django-polls`` as a system library. In
     243   general, it's best to avoid messing with your system libraries to avoid
     244   breaking things. For this simple example though, the risk is low and it will
     245   help with understanding packaging. We'll explain how to uninstall in
     246   step 4.
     247
     248   For experienced users, a neater way to manage your packages is to use
     249   "virtualenv" (see below).
     250
     2511. Inside ``django-polls/dist``, untar the new package
     252   ``django-polls-0.1.tar.gz`` (e.g. ``tar xzvf django-polls-0.1.tar.gz``). If
     253   you're using Windows, you can download the command-line tool bsdtar_ to do
     254   this, or you can use a GUI-based tool such as 7-zip_.
     255
     2562. Change into the directory created in step 1 (e.g. ``cd django-polls``).
     257
     2583. If you're using GNU/Linux, Mac OS X or some other flavor of Unix, enter the
     259   command ``sudo python setup.py install`` at the shell prompt.  If you're
     260   using Windows, start up a command shell with administrator privileges and
     261   run the command ``setup.py install``.
     262
     263   With luck, your Django project should now work correctly again. Run the
     264   server again to confirm this.
     265
     2664. To uninstall the package, delete the polls-related directories and files from
     267   your system libraries. To find them, run the following at your Python prompt.
     268
     269   >>> import polls
     270   >>> polls
     271   <module 'polls' from '/usr/local/lib/python2.7/dist-packages/polls/__init__.pyc'>
     272
     273   In this case, we would find the polls-related files and directories in
     274   ``/usr/local/lib/python2.7/dist-packages/``. Your location may be different.
     275
     276.. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
     277.. _7-zip: http://www.7-zip.org/
     278
     279Publishing your app
     280===================
     281
     282Now that we've packaged and tested ``django-polls``, it's ready to share with
     283the world! If this wasn't just an example, you could now:
     284
     285* Email the package to a friend.
     286
     287* Upload the package on your Web site.
     288
     289* Post the package on a public repository, such as `The Python Package Index
     290  (PyPI) <http://guide.python-distribute.org/contributing.html#pypi-info>`_.
     291
     292For more information on PyPI, see the `Quickstart
     293<http://guide.python-distribute.org/quickstart.html#register-your-package-with-the-python-package-index-pypi>`_
     294section of The Hitchhiker's Guide to Packaging. One detail this guide mentions
     295is choosing the license under which your code is distributed.
     296
     297Installing Python packages with virtualenv
     298==========================================
     299
     300Earlier, we installed the polls app as a system library. This has some
     301
     302* Modifying the system libraries can affect other Python software on your
     303  system.
     304
     305* You won't be able to run multiple versions of this package (or others with
     306  the same name).
     307
     308Typically, these situations only arise once you're maintaining several Django
     309projects. When they do, the best solution is to use *virtualenv*. This tool
     310allows you to maintain multiple isolated Python environments, each with its own
     311copy of the libraries and package namespace.
     312
     313Learn more on the `virtualenv <http://www.virtualenv.org/>`_ Web site.
     314
     315More about reusable apps
     316========================
     317
     318For more on writing reusable apps, see `What is a reusable app?
     319<http://ericholscher.com/projects/django-conventions/app/>`_ by Eric
     320Holsher. For a collection of reusable apps to use in your own projects, see the
     321`Pinax <http://pinaxproject.com/>`_ project.
     322
     323The tutorial ends here for the time being. In the meantime, you might want to
     324check out some pointers on :doc:`where to go from here </intro/whatsnext>`.
  • new file tutorial05.diff

    diff --git a/tutorial05.diff b/tutorial05.diff
    new file mode 100644
    index 0000000..592e2b6
    - +  
     1diff --git a/AUTHORS b/AUTHORS
     2index 5fa9578..151e8a4 100644
     3--- a/AUTHORS
     4+++ b/AUTHORS
     5@@ -378,6 +378,7 @@ answer newbie questions, and generally made Django that much better:
     6     Christian Metts
     7     michal@plovarna.cz
     8     Slawek Mikula <slawek dot mikula at gmail dot com>
     9+    Katie Miller <katie@sub50.com>
     10     Shawn Milochik <shawn@milochik.com>
     11     mitakummaa@gmail.com
     12     Taylor Mitchell <taylor.mitchell@gmail.com>
     13@@ -506,6 +507,7 @@ answer newbie questions, and generally made Django that much better:
     14     Johan C. Stöver <johan@nilling.nl>
     15     Nowell Strite <http://nowell.strite.org/>
     16     Thomas Stromberg <tstromberg@google.com>
     17+    Ben Sturmfels <ben@sturm.com.au>
     18     Pascal Varet
     19     SuperJared
     20     Radek Švarz <http://www.svarz.cz/translate/>
     21diff --git a/docs/index.txt b/docs/index.txt
     22index 3f4e303..6979979 100644
     23--- a/docs/index.txt
     24+++ b/docs/index.txt
     25@@ -44,7 +44,8 @@ Are you new to Django or to programming? This is the place to start!
     26   :doc:`Part 1 <intro/tutorial01>` |
     27   :doc:`Part 2 <intro/tutorial02>` |
     28   :doc:`Part 3 <intro/tutorial03>` |
     29-  :doc:`Part 4 <intro/tutorial04>`
     30+  :doc:`Part 4 <intro/tutorial04>` |
     31+  :doc:`Part 5 <intro/tutorial05>`
     32 
     33 The model layer
     34 ===============
     35diff --git a/docs/intro/index.txt b/docs/intro/index.txt
     36index 19290a5..186727b 100644
     37--- a/docs/intro/index.txt
     38+++ b/docs/intro/index.txt
     39@@ -13,6 +13,7 @@ place: read this material to quickly get up and running.
     40    tutorial02
     41    tutorial03
     42    tutorial04
     43+   tutorial05
     44    whatsnext
     45   
     46 .. seealso::
     47@@ -33,4 +34,4 @@ place: read this material to quickly get up and running.
     48     .. _list of Python resources for non-programmers: http://wiki.python.org/moin/BeginnersGuide/NonProgrammers
     49     .. _dive into python: http://diveintopython.net/
     50     .. _dead-tree version: http://www.amazon.com/exec/obidos/ASIN/1590593561/ref=nosim/jacobian20
     51-    .. _books about Python: http://wiki.python.org/moin/PythonBooks
     52\ No newline at end of file
     53+    .. _books about Python: http://wiki.python.org/moin/PythonBooks
     54diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt
     55index 49e597c..2445de4 100644
     56--- a/docs/intro/tutorial04.txt
     57+++ b/docs/intro/tutorial04.txt
     58@@ -331,18 +331,5 @@ Run the server, and use your new polling app based on generic views.
     59 For full details on generic views, see the :doc:`generic views documentation
     60 </topics/class-based-views/index>`.
     61 
     62-Coming soon
     63-===========
     64-
     65-The tutorial ends here for the time being. Future installments of the tutorial
     66-will cover:
     67-
     68-* Advanced form processing
     69-* Using the RSS framework
     70-* Using the cache framework
     71-* Using the comments framework
     72-* Advanced admin features: Permissions
     73-* Advanced admin features: Custom JavaScript
     74-
     75-In the meantime, you might want to check out some pointers on :doc:`where to go
     76-from here </intro/whatsnext>`
     77+When you're comfortable, read :doc:`part 5 of this tutorial
     78+</intro/tutorial05>` to learn about turning Polls into a reusable app.
     79diff --git a/docs/intro/tutorial05.txt b/docs/intro/tutorial05.txt
     80new file mode 100644
     81index 0000000..85ef56e
     82--- /dev/null
     83+++ b/docs/intro/tutorial05.txt
     84@@ -0,0 +1,324 @@
     85+=====================================
     86+Writing your first Django app, part 5
     87+=====================================
     88+
     89+This tutorial begins where :doc:`Tutorial 4 </intro/tutorial04>` left
     90+off. We'll be turning our Web-poll into a standalone Python package you can
     91+reuse in new projects and share with other people.
     92+
     93+If you haven't recently completed Tutorials 1–4, we encourage you to review
     94+these so that your example project matches the one described below.
     95+
     96+.. Outline:
     97+
     98+.. * motivation
     99+..     * what is a python package?
     100+..     * what is a django app?
     101+..     * what is a reusable app?
     102+
     103+.. * preparing
     104+..     * moving templates into your app
     105+..     * parent directory
     106+..     * adding package boilerplate
     107+..     * link to packaging docs
     108+..     * package builder
     109+
     110+.. * using the package
     111+..     * how to install
     112+
     113+.. * publishing
     114+..     * options for publishing
     115+..     * link to docs on PyPI
     116+
     117+Reusability matters
     118+===================
     119+
     120+It's a lot of work to design, build, test and maintain a web application. Many
     121+Python and Django projects share common problems. Wouldn't it be great if we
     122+could save some of this repeated work?
     123+
     124+Reusability is the way of life in Python. `The Python Package Index (PyPI)
     125+<http://guide.python-distribute.org/contributing.html#pypi-info>`_ has a vast
     126+range of packages you can use in your own Python programs. Django itself is
     127+also just a Python package. This means that you can take existing Python
     128+packages or Django apps and compose them into your own web project. You only
     129+need to write the parts that make your project unique.
     130+
     131+Let's say you were starting a new project that needed a polls app like the one
     132+we've been working on. How do you make this app reusable? Luckily, you're well
     133+on the way already. In the :doc:`Tutorial 3 </intro/tutorial03>`, we began by
     134+decoupling polls from the project-level URLconf. In this tutorial, we'll take
     135+further steps to make the app easy to use in new projects and ready to publish
     136+for others to install and use.
     137+
     138+.. admonition:: Package? App?
     139+
     140+    A Python `package <http://docs.python.org/tutorial/modules.html#packages>`_
     141+    provides a way of grouping related Python code for easy reuse. A package contains
     142+    one or more files of Python code (also known as "modules").
     143+
     144+    A package can be imported with ``import foo.bar`` or ``from foo import
     145+    bar``. For a directory (like ``polls``) to form a package, it must contain a
     146+    special file ``__init__.py``, even if this file is empty.
     147+
     148+    A Django *app* is just a Python package that is specifically intended for
     149+    use in a Django project. An app may also use common Django conventions,
     150+    such as having a ``models.py`` file.
     151+
     152+    Later on we use the term *packaging* to describe the process of making a
     153+    Python package easy for others to install. It can be a little confusing, we
     154+    know.
     155+
     156+Completing your reusable app
     157+============================
     158+
     159+After the previous tutorials, our project should look like this::
     160+
     161+    mysite/
     162+        manage.py
     163+        mysite/
     164+            __init__.py
     165+            settings.py
     166+            urls.py
     167+            wsgi.py
     168+        polls/
     169+            admin.py
     170+            __init__.py
     171+            models.py
     172+            tests.py
     173+            urls.py
     174+            views.py
     175+
     176+You also have a directory somewhere called ``mytemplates`` which you created in
     177+:doc:`Tutorial 2 </intro/tutorial02>`. You specified its location in the
     178+TEMPLATE_DIRS setting. This directory should look like this::
     179+
     180+    mytemplates/
     181+        admin/
     182+            base_site.html
     183+        polls/
     184+            detail.html
     185+            index.html
     186+            results.html
     187+
     188+The polls app is already a Python package, thanks to the ``polls/__init__.py``
     189+file. That's a great start, but we can't just pick up this package and drop it
     190+into a new project. The polls templates are currently stored in the
     191+project-wide ``mytemplates`` directory. To make the app self-contained, it should also contain the necessary templates.
     192+
     193+Inside the ``polls`` app, create a new ``templates`` directory. Now move the
     194+``polls`` template directory from ``mytemplates`` into the new
     195+``templates``. Your project should now look like this::
     196+
     197+    mysite/
     198+        manage.py
     199+        mysite/
     200+            __init__.py
     201+            settings.py
     202+            urls.py
     203+            wsgi.py
     204+        polls/
     205+            admin.py
     206+            __init__.py
     207+            models.py
     208+            templates/
     209+                polls/
     210+                    detail.html
     211+                    index.html
     212+                    results.html
     213+            tests.py
     214+            urls.py
     215+            views.py
     216+
     217+Your project-wide templates directory should now look like this::
     218+
     219+    mytemplates/
     220+        admin/
     221+            base_site.html
     222+
     223+Looking good! Now would be a good time to confirm that your polls application
     224+still works correctly.
     225+
     226+The ``polls`` directory could now be copied into a new Django project and
     227+immediately reused. It's not quite ready to be published though. For that, we
     228+need to package the app to make it easy for others to install.
     229+
     230+.. admonition:: Why nested?
     231+
     232+   Why create a ``polls`` directory under ``templates`` when we're
     233+   already inside the polls app? This directory is needed to avoid conflicts in
     234+   Django's ``app_directories`` template loader.
     235+
     236+Packaging your app
     237+==================
     238+
     239+Python *packaging* refers to preparing your app in a specific format that can
     240+be easily installed and used. Django itself is packaged very much like
     241+this. For a small app like polls, this process isn't too difficult.
     242+
     243+1. Firstly, create a parent directory for ``polls``, outside of your Django
     244+   project. Call this directory ``django-polls``.
     245+
     246+2. Move the ``polls`` directory into the ``django-polls`` directory.
     247+
     248+3. Create a file ``django-polls/README.txt`` with the following contents::
     249+
     250+       =====
     251+       Polls
     252+       =====
     253+
     254+       Polls is a simple Django app to conduct Web-based polls. For each
     255+       question, visitors can choose between a fixed number of answers.
     256+
     257+       Detailed documentation is in the "docs" directory.
     258+
     259+       Quick start
     260+       -----------
     261+
     262+       1. Add "polls" to your INSTALLED_APPS setting like this::
     263+
     264+              INSTALLED_APPS = (
     265+                  ...
     266+                  'polls',
     267+              )
     268+
     269+       2. Include the polls URLconf in your project urls.py like this::
     270+
     271+              (r'^polls/', include('polls.urls')),
     272+
     273+       3. Run `python manage.py syncdb` to create the polls models.
     274+
     275+       4. Start the development server and visit http://127.0.0.1:8000/admin/
     276+          to create a poll (you'll need the Admin app enabled).
     277+
     278+       5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
     279+
     280+
     281+5. Create a file ``django-polls/setup.py`` with the following contents::
     282+
     283+    from distutils.core import setup
     284+
     285+    setup(
     286+        name='django-polls',
     287+        version='0.1',
     288+        packages=['polls',],
     289+       license='',
     290+        long_description=open('README.txt').read(),
     291+        url='http://www.example.com/',
     292+        author='Your Name',
     293+        author_email='yourname@example.com',
     294+    )
     295+
     296+6. Only a limited set of files are included in the package by default. To also
     297+   include the templates, create a file ``django-polls/MANIFEST.in`` with
     298+   the following contents::
     299+
     300+       recursive-include polls/templates *
     301+
     302+7. It's optional, but recommended, to include detailed documentation with your
     303+   app. Create an empty directory ``django-polls/docs`` for future
     304+   documentation. Add an additional line to ``django-polls/MANIFEST.in``::
     305+
     306+       recursive-include docs *
     307+
     308+   Note that the ``docs`` directory won't be included in your package unless you
     309+   add some files to it.
     310+
     311+8. Try building your package with ``python setup.py sdist`` (run from inside
     312+   ``django-polls``). This creates a directory called ``dist`` and builds your
     313+   new package, ``django-polls-0.1.tar.gz``.
     314+
     315+For more information on packaging, see `The Hitchhiker's Guide to Packaging
     316+<http://guide.python-distribute.org/quickstart.html>`_.
     317+
     318+Using your own package
     319+======================
     320+
     321+Since we moved the ``polls`` directory out of the project, it's no longer
     322+working. We'll now fix this by installing our new ``django-polls`` package.
     323+
     324+.. admonition:: Installing as a system library
     325+
     326+   The following steps install ``django-polls`` as a system library. In
     327+   general, it's best to avoid messing with your system libraries to avoid
     328+   breaking things. For this simple example though, the risk is low and it will
     329+   help with understanding packaging. We'll explain how to uninstall in
     330+   step 4.
     331+
     332+   For experienced users, a neater way to manage your packages is to use
     333+   "virtualenv" (see below).
     334+
     335+1. Inside ``django-polls/dist``, untar the new package
     336+   ``django-polls-0.1.tar.gz`` (e.g. ``tar xzvf django-polls-0.1.tar.gz``). If
     337+   you're using Windows, you can download the command-line tool bsdtar_ to do
     338+   this, or you can use a GUI-based tool such as 7-
     339 No newline at end of file
Back to Top