Format and wording tweaks

Author: brettcannon

source/packaging_tutorial.txt

@@ -17,19 +17,21 @@ Installing setuptools
 Lay out your project
 ====================
 
-The smallest python project is two files. A :ref:`setup.py
+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.
 
 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.
+project to provide the typical minimal layout of a project. We will call our
+project TowelStuff and keep it in a directory with the same name.
+We'll create a full Python package called
+:ref:`towelstuff/ <towelstuff_description>` as a directory with an
+`__init__.py` file. 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
+file giving an overview of your project, and
 a :ref:`LICENSE.txt <license_txt_description>` file containing the
 license of your project.
 
@@ -55,23 +57,31 @@ project. It describes all of the metadata about your project. 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.
+if you wish to publish your package on the
+:ref:`Python Package Index (PyPI) <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. The `classifiers` field lists
+various facts about your project, e.g. what versions of Python it is
+compatible with.
 
 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
 
+    with open('README.txt') as file:
+        long_description = file.read()
+
     setup(
         name='TowelStuff',
         version='0.1.dev1',
         packages=['towelstuff',],
         license='Creative Commons Attribution-Noncommercial-Share Alike license',
-        long_description=open('README.txt').read(),
+        long_description=long_description,
+        classifiers=[
+            'Programming Language :: Python :: 3.3',
+        ],
     )
 
 
@@ -90,11 +100,11 @@ Create your first release
 In the `version` field, we specified `0.1.dev1`. This indicates that we
 are *developing* towards the `0.1` version. Right now there isn't any code
 in the project. After you've written enough code to make your first release
-worthwhile, you will change the version field to just `0.1`, dropping the `.dev1`
-marker.
+worthwhile, you will change the version field to just `0.1`, dropping the
+`.dev1` marker.
 
 To create a release, your source code needs to be packaged into a single
-archive file. This can be done with the `sdist` command:
+archive file for distribution. This can be done with the `sdist` command:
 
  $ python setup.py sdist
 
@@ -110,15 +120,15 @@ and `.zip` files on Windows systems.
 By default, Distutils does **not** include all files in your project's
 directory. Only the following files will be included by default:
 
- * all Python source files implied by the py_modules and packages options
+ * all Python source files implied by the `py_modules` and `packages` options
 
- * all C source files mentioned in the ext_modules or libraries options
+ * all C source files mentioned in the `ext_modules` or `libraries` options
 
- * scripts identified by the scripts option
+ * scripts identified by the `scripts` option
 
  * anything that looks like a test script: test/test*.py
 
- * Top level files named: README.txt, README, setup.py, or setup.cfg
+ * Top level files named: `README.txt`, `README`, `setup.py`, or `setup.cfg`
 
 If you want to include additional files, then there are a couple options
 for including those files:
@@ -127,11 +137,11 @@ for including those files:
    Setuptools allows you to include all files checked into
    your version control system.
 
- * Write a top-level MANIFEST.in file. This is a template file which
+ * Write a top-level `MANIFEST.in` file. This is a template file which
    specifies which files (and file patterns) should be included.
    (TO-DO: link to a MANIFEST.in document)
 
-When you run the **sdist** command, a file named MANIFEST will be
+When you run the **sdist** command, a file named `MANIFEST` will be
 generated which contains a complete list of all files included. You can
 view this file to double check that you've setup your project to include
 all files correctly. Now your project is ready for a release. Before
@@ -179,7 +189,7 @@ 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
+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::