Anonymous avatar Anonymous committed 7167cdd

Rework the Quick Start so it covers a bit less, but in more detail for the topics it covers.

Comments (0)

Files changed (1)

source/quickstart.txt

 1. Lay out your project's main directory
 ========================================
 
-Under the main directory, you'll **need** a :ref:`setup.py
-<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 <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.
+The smallest python project is two files. A :ref:`setup.py
+<setup_py_description>` file which describes the metadata about your project,
+and a file containing Python code to implement the functionality of your
+project.
 
-We **highly recommend** a :ref:`README.txt <readme_txt_description>`
-file describing your project and where to go for more information, and
+In this example project we are going to add a little more to the 
+project to provide the typical minimal layout of a project. We'll create
+a full Python package, a directory with an `__init__.py` file, called
+:ref:`towelstuff/ <towelstuff_description>`. This anticipates future growth
+as our project's source code is likely to grow beyond a single module file.
+
+We'll also create a :ref:`README.txt <readme_txt_description>`
+file describing an overview of your project, 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.
+That's enough to start. There are a number of other types of files a
+project will often have, see the :ref:`directory_layout` for an example of
+a more fully fleshed out project.
 
-.. note:: For full details, look at :ref:`directory_layout`.
+Your project will now look like::
 
-2. Register your package with the Python Package Index (PyPI)
+    TowelStuff/
+        LICENSE.txt
+        README.txt
+        setup.py
+        towelstuff/
+            __init__.py
+
+2. Describe your project in the setup.py file
+=============================================
+
+There a quite a few fields you can add to a project to give it a rich set of
+metadata describing the project. However, there are only three required
+fields: `name`, `version`, and `packages`. The `name` field must be unique
+if you wish to publish your package on the Python Package Index (PyPI).
+The `version` field keeps track of different releases of the project. The
+`packages` field describes where you've put the Python source code within
+your project.
+
+Our initial `setup.py` will also include information about the license
+and will re-use the `README.txt` file for the `long_description` field.
+This will look like::
+
+    from distutils.core import setup
+
+    setup(
+        name='TowelStuff',
+        version='0.1dev',
+        packages=['towelstuff',],
+        license='Creative Commons Attribution-Noncommercial-Share Alike license',
+        long_description=open('README.txt').read(),
+    )
+
+
+3. Register your package with the Python Package Index (PyPI)
 =============================================================
 
-To register your package on the :ref:`pypi_info`, run ::
+There is a central index of all publically available Python projects
+maintained on the python.org web site named the :ref:`pypi_info`. You
+will first have to visit that site, where you can register for an account.
+Project's are published on PyPI in the format of::
+
+    http://pypi.python.org/pypi/<projectname>
+
+Your project will have to choose a name which is not already taken on PyPI.    
+You can then claim your new project's name by registering the package
+by running the command::
 
  $ python setup.py register
 
-.. note:: You may need to do this every time you change ``README.txt``.
 
-3. For each release, build and upload the package
-=================================================
+4. Build and check a release
+============================
 
-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. ::
+In the `version` field, we specified `0.1dev`. This indicates that we
+are *developing* towards the `0.1` version. Right now there isn't any code
+in the project. You would first write enough code to make your first release
+worthwhile, then change the version field to just `0.1`, dropping the `dev`
+marker.
 
- $ python setup.py sdist bdist_msi upload
+To create a release, your source code needs to be packaged into a single
+archive file. This can be done with the `sdist` command:
 
-4. Go find some users
-=====================
+ $ python setup.py sdist
+ 
+This will create a `dist` sub-directory in your project, and will wrap-up
+all of your project's source code files into a distribution file,
+a compressed archive file in the form of::
+
+    TowelStuff-0.1.tar.gz
+
+The compressed archive format defaults to `.tar.gz` files on POSIX systems,
+and `.zip` files on Windows systems.
+
+At this point, it's a good idea to uncompress the newly created source
+distribution, and make sure everything is being packaged correctly. There
+are a two important points to check to make sure your package is ready for release:
+
+* The correct version number.
+
+  While it's handy to append a `dev` marker to the version number during
+  development, so that you can distinguish between code under development
+  and a released version, you **never** want to publish a release with
+  `dev` in the version name.
+
+* All desired project files are included.
+
+  This is a big one. There are a variety of different ways of indicating
+  which files from your project should be included in the release, and which
+  should not. For a full overview see `specifying the files to distribute
+  <http://docs.python.org/distutils/sourcedist.html#specifying-the-files-to-distribute>`_.
+
+  In our minimal example, we used the `packages` field describes a list of
+  packages that are included as part of your project. If we created a 
+  `towelstuff.test` package, we would need to explicitly add that package
+  name to our `packages` field, so that it looked like::
+
+    packages=['towelstuff','towelstuff.test'],
+
+  You will also notice that the README.txt and LICENSE.txt files are not
+  included as part of distribution - unless those files have checked into
+  Subversion. If you aren't using Subversion for source code management,
+  then you will either need to specify those files using a `MANIFEST.in`
+  file (or use Distribute with a plug-in appropriate for your source code tool).
+
+
+5. Upload your release, then grab your towel and save the Universe!
+===================================================================
+
+Now that you are happy that you can create a valid source distribution,
+it's time to upload the finished product to PyPI. We'll also create a 
+`bdist_wininst` distribution file of our project, which will create a Windows
+installable file. There are a few different file formats that Python 
+distributions can be created for. Each format must be specified when
+you run the upload command, or they won't be uploaded (even if you've
+previously built them previously). You should always upload a
+source distribution file. The other formats are optional, and will depend upon
+the needs of your anticipated user base::
+
+ $ python setup.py sdist bdist_wininst upload
 
 At this point you should announce your package to the community!
 
-5. Grab Your Towel and Save the Universe!
-=========================================
+Finally, in your `setup.py` you can make plans for your next release,
+by changing the `version` field to indicate which version you want to work
+towards next (e.g. `0.2dev`).
 
 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`,
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.