hhgp / source / quickstart.txt

Quick Start

Here's how to create a new project, which we'll call **TowelStuff**.

1. Lay out your project's main directory

Under the main directory, you'll **need** a :ref:`
<setup_py_description>` and at least one package directory,
:ref:`towelstuff/ <towelstuff_description>` (which is what's actually
imported when you do ``import towelstuff``).  You will also need a
:ref:` <manifest_in_description>` to bundle non-source
files in the distribution -- unless you're using Subversion.  (Don't
ask.)  If you have any command line scripts, put them in the
:ref:`bin/ <bin_description>` directory.

We **highly recommend** a :ref:`README.txt <readme_txt_description>`
file describing your project and where to go for more information, and
a :ref:`LICENSE.txt <license_txt_description>` file containing the
license of your project.

If you want full marks on your project, please also include a
:ref:`CHANGES.txt <changes_txt_description>`
and a :ref:`docs/ <docs_description>` directory containing any documentation.

.. note:: For full details, look at :ref:`directory_layout`.

2. Register your package with the Python Package Index (PyPI)

To register your package on the :ref:`pypi_info`, run ::

 $ python register

.. note:: You may need to do this every time you change ``README.txt``.

3. For each release, build and upload the package

Whenever you release a new version, build your package and then upload
it to PyPI.  The following command line will create a source distribution
and Windows binary installer, and then upload both of them to PyPI. ::

 $ python sdist bdist_msi upload

4. Go find some users

At this point you should announce your package to the community!

5. Grab Your Towel and Save the Universe!

This `Quick Start`_ is a good brief introduction, but does not cover a lot of
obscure use-cases. For more details, please see :doc:`introduction`,
to gain a better understanding of the :ref:`state_of_packaging_info`.