Ticket #16671: tutorial05.3.diff

File tutorial05.3.diff, 12.3 KB (added by stumbles, 9 years ago)

Extended README.txt, include "docs" in package and update tutorial index links.

  • AUTHORS

    diff -r 548df236b2cc AUTHORS
    a b  
    357357    Christian Metts
    358358    michal@plovarna.cz
    359359    Slawek Mikula <slawek dot mikula at gmail dot com>
     360    Katie Miller <katie@sub50.com>
    360361    Shawn Milochik <shawn@milochik.com>
    361362    mitakummaa@gmail.com
    362363    mmarshall
     
    474475    Johan C. Stöver <johan@nilling.nl>
    475476    Nowell Strite <http://nowell.strite.org/>
    476477    Thomas Stromberg <tstromberg@google.com>
     478    Ben Sturmfels <ben@stumbles.id.au>
    477479    Pascal Varet
    478480    SuperJared
    479481    Radek Švarz <http://www.svarz.cz/translate/>
  • docs/index.txt

    diff -r 548df236b2cc docs/index.txt
    a b  
    4242      :doc:`Part 1 <intro/tutorial01>` |
    4343      :doc:`Part 2 <intro/tutorial02>` |
    4444      :doc:`Part 3 <intro/tutorial03>` |
    45       :doc:`Part 4 <intro/tutorial04>`
     45      :doc:`Part 4 <intro/tutorial04>` |
     46      :doc:`Part 5 <intro/tutorial05>`
    4647
    4748The model layer
    4849===============
  • docs/intro/index.txt

    diff -r 548df236b2cc docs/intro/index.txt
    a b  
    1313   tutorial02
    1414   tutorial03
    1515   tutorial04
     16   tutorial05
    1617   whatsnext
    1718   
    1819.. seealso::
     
    3334    .. _list of Python resources for non-programmers: http://wiki.python.org/moin/BeginnersGuide/NonProgrammers
    3435    .. _dive into python: http://diveintopython.org/
    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 -r 548df236b2cc docs/intro/tutorial04.txt
    a b  
    322322For full details on generic views, see the :doc:`generic views documentation
    323323</topics/http/generic-views>`.
    324324
    325 Coming soon
    326 ===========
    327 
    328 The tutorial ends here for the time being. Future installments of the tutorial
    329 will cover:
    330 
    331     * Advanced form processing
    332     * Using the RSS framework
    333     * Using the cache framework
    334     * Using the comments framework
    335     * Advanced admin features: Permissions
    336     * Advanced admin features: Custom JavaScript
    337 
    338 In the meantime, you might want to check out some pointers on :doc:`where to go
    339 from here </intro/whatsnext>`
     325When you're comfortable, read :doc:`part 5 of this tutorial
     326</intro/tutorial05>` to learn about turning Polls into a reusable app.
  • new file docs/intro/tutorial05.txt

    diff -r 548df236b2cc docs/intro/tutorial05.txt
    - +  
     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 stand-alone Python package.
     7
     8.. Outline:
     9
     10.. * motivation
     11..     * what is a python package?
     12..     * what is a django app?
     13..     * what is a reusable app?
     14
     15.. * preparing
     16..     * moving templates into your app
     17..     * parent directory
     18..     * adding package boilerplate
     19..     * link to packaging docs
     20..     * package builder
     21
     22.. * using the package
     23..     * how to install
     24
     25.. * publishing
     26..     * options for publishing
     27..     * link to docs on PyPI
     28
     29Python packages and reusable apps
     30==================================
     31
     32Django really is just Python. This means that you can make use of existing
     33Python packages in your project. You can also take parts of your projects and
     34reuse or share them.
     35
     36.. note::
     37
     38    A Python `package <http://docs.python.org/tutorial/modules.html#packages>`_
     39    is a way of grouping related Python code for easy reuse. A package contains
     40    one or more files of Python code (also known as "modules").
     41
     42    A Django *app* is nothing more than a Python package intended for use in a
     43    Django project. An app may also use common Django conventions, such as
     44    having a ``models.py`` file.
     45
     46One of Django's most powerful features is the concept of *reusable apps*. The
     47idea is that rather than rebuilding every new Django project from scratch, you
     48can make use of existing packages that you, and others, have written.
     49
     50In fact, we're already halfway to a reusable app. The Polls app we've been
     51working on is already a Python package. We know this because it can be imported
     52with ``import polls`` (since it contains an ``__init__.py`` file). In the
     53previous tutorials, we began making Polls reusable by decoupling it from the
     54project-level URLconf.
     55
     56In this tutorial, we'll take further steps to make the app easily to use in new
     57projects and ready to publish for others to install and use.
     58
     59Completing your reusable app
     60============================
     61
     62Currently the Poll templates are stored in the project-wide ``templates``
     63directory. To make it reusable, we need to store these templates within the app
     64itself.
     65
     66Inside ``mysite/polls``, create the directory ``templates`` and *inside* that,
     67the directory ``polls``. Move the ``index.html`` and ``detail.html`` templates
     68into ``templates/polls``. This allows the app's templates to be distributed
     69with the app. Confirm that your poll Web site still works correctly.
     70
     71Your project should now look like this::
     72
     73    mysite/
     74        polls/
     75            admin.py
     76            templates/
     77                polls/
     78                    detail.html
     79                    index.html
     80            __init__.py
     81            models.py
     82            tests.py
     83            urls.py
     84            views.py
     85        __init__.py
     86        manage.py
     87        settings.py
     88        urls.py
     89
     90.. NOTE:: Why create a ``polls`` directory under templates when we're already
     91   inside the Polls app? This directory is needed to avoid conflicts because of
     92   how Django's ``app_directories`` template loader works.
     93
     94You now have a package that could be copied into new Django projects and
     95immediately reused. It's not yet ready to be published though. For that, we
     96need to package the app to make it easy for others to install.
     97
     98Packaging your app
     99==================
     100
     101Python packaging isn't as hard as it sounds, especially for such a small app.
     102
     1031. Firstly, create a parent directory for ``polls``, outside of your Django
     104   project. Call this directory ``django-polls``.
     105
     1062. Move the ``polls`` directory into the ``django-polls`` directory.
     107
     1083. Create a file ``django-polls/README.txt`` with the following contents::
     109
     110       =====
     111       Polls
     112       =====
     113
     114       Polls is a simple Django app to conduct Web-based polls. For each
     115       question, visitors can choose between a fixed number of answers.
     116
     117       Detailed documentation is in the "docs" directory.
     118
     119       Quick start
     120       -----------
     121
     122       1. Add "polls" to your INSTALLED_APPS setting like this::
     123
     124              INSTALLED_APPS = (
     125                  ...
     126                  'polls',
     127              )
     128
     129       2. Include the polls URLconf in your project urls.py like this::
     130
     131              (r'^polls/', include('polls.urls')),
     132
     133       3. Run `python manage.py syncdb` to create the polls models.
     134
     135       4. Start the development server and visit http://127.0.0.1:8000/admin/
     136          to create a poll (you'll need the Admin app enabled).
     137
     138       5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
     139
     140
     1415. Create a file ``django-polls/setup.py`` with the following contents::
     142
     143    from distutils.core import setup
     144
     145    setup(
     146        name='django-polls',
     147        version='0.1',
     148        packages=['polls',],
     149        license='',
     150        long_description=open('README.txt').read(),
     151        url='http://www.example.com/',
     152        author='Your Name',
     153        author_email='yourname@example.com',
     154    )
     155
     1566. It's optional, but recommended, to include detailed documentation with
     157   your app. Create an empty directory ``django-polls/docs`` for future
     158   documentation. Create a file ``django-polls/MANIFEST.in`` with the following
     159   contents::
     160
     161       recursive-include docs *
     162
     163   This instruction ensures that the ``docs`` directory is included in the
     164   package.
     165
     1667. Try building your package with ``python setup.py sdist`` (run from inside
     167   ``django-polls``. This creates a directory called ``dist`` and builds your
     168   new package, ``django-polls-0.1.tar.gz``.
     169
     170For more information on packaging, see `The Hitchhiker's Guide to Packaging
     171<http://guide.python-distribute.org/quickstart.html>`_.
     172
     173Using your own package
     174======================
     175
     176Since we moved the ``polls`` directory out of the project, it's no longer
     177working. We'll now fix this by installing our new ``django-polls`` package.
     178
     179.. NOTE:: The following steps install ``django-polls`` as a system library. In
     180   general, it's best to avoid messing with your system libraries to avoid
     181   breaking things. For this simple example though, the risk is low and it will
     182   help with understanding packaging. We'll explain how to uninstall in
     183   step 4.
     184
     185   For experienced users, a neater way to manage your packages is to use
     186   "virtualenv" (see below).
     187
     1881. Inside ``django-polls/dist``, untar the new package
     189   ``django-polls-0.1.tar.gz`` (e.g. ``tar xzvf django-polls-0.1.tar.gz``). If
     190   you're using Windows, you can download the command-line tool bsdtar_ to do
     191   this, or you can use a GUI-based tool such as 7-zip_.
     192
     1932. Change into the directory created in step 1 (e.g. ``cd django-polls``).
     194
     1953. If you're using GNU/Linux, Mac OS X or some other flavor of Unix, enter the
     196   command ``sudo python setup.py install`` at the shell prompt.  If you're
     197   using Windows, start up a command shell with administrator privileges and
     198   run the command ``setup.py install``.
     199
     200   With luck, your Django project should now work correctly again. Run the
     201   server again to confirm this.
     202
     2034. To uninstall the package, delete the directory ``polls`` and the file
     204   ``django_polls-0.1.egg-info`` from your system libraries. On GNU/Linux and
     205   Mac OS these files live in ``/usr/local/lib/python2.X/dist-packages``, and
     206   on Windows, in ``C:\Python2X\Lib\site-packages`` (where *X* is the Python
     207   minor version number). You will need administrator privileges.
     208
     209.. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
     210.. _7-zip: http://www.7-zip.org/
     211
     212Publishing your app
     213===================
     214
     215Now that we've packaged and tested ``django-polls``, it's ready to share with
     216the world! If this wasn't just an example, you could now:
     217
     218    * Email the package to a friend.
     219
     220    * Upload the package on your Web site.
     221
     222    * Post the package on a public repository, such as `The Python Package
     223      Index (PyPI)
     224      <http://guide.python-distribute.org/contributing.html#pypi-info>`_.
     225
     226For more information on PyPI, see the `Quickstart
     227<http://guide.python-distribute.org/quickstart.html#register-your-package-with-the-python-package-index-pypi>`_
     228section of The Hitchhiker's Guide to Packaging. One detail this guide mentions
     229is choosing the license under which your code is distributed.
     230
     231Installing Python packages with virtualenv
     232==========================================
     233
     234Earlier, we installed the Polls app as a system library. This has some
     235disadvantages:
     236
     237    * Modifying the system libraries can affect other Python software on your
     238      system.
     239
     240    * You won't be able to run multiple version of this package (or others with
     241      the same name).
     242
     243Typically, these situations only arise once you're maintaining several Django
     244projects. When they do, the best solution is to use `virtualenv
     245<http://www.virtualenv.org/>`_. This tool allows you to maintain multiple
     246isolated Python environments, each with its own copy of the libraries and
     247package namespace.
     248
     249Further information
     250===================
     251
     252For more on writing reusable apps, see `What is a reusable app?
     253<http://ericholscher.com/projects/django-conventions/app/>`_ by Eric
     254Holsher. For a collection of reusable apps to use in your own projects, see the
     255`Pinax <http://pinaxproject.com/>`_ project.
     256
     257The tutorial ends here for the time being. In the meantime, you might want to
     258check out some pointers on :doc:`where to go from here </intro/whatsnext>`.
Back to Top