Updated INSTALL and install documentation to be released oriented

INSTALL

@@ -1,69 +1,85 @@
-We have two different approaches to installing Pinax. The best approach is to
-download our stable release and follow the "Released tarball instructions".
-The benefit to this approach is that it requires absolutely no Internet
-connection once you have downloaded the tarball.
+This covers installation from a release bundle. For information on installing
+a development version, see http://pinaxproject.com/docs/dev/contributing.html.
 
-The alternative approach is to start from the development version. You can
-take this approach by following the "Development instructions". This means
-you will be working with the bleeding edge of our code. We can not guarantee
-any stability.
+The release bundle has almost everything you need to get Pinax up and running.
+The only things not included are Python itself, the Python Imaging Library
+(PIL) and a database such as SQLite (which is included in Python 2.5+).
 
-.. note::
+For more information on installing PIL, see
+http://pinaxproject.com/docs/0.7/pil.html.
 
-    If you are on OS X be sure you have the Apple developer tools installed.
+If you are on Mac OS X, make sure you have the Apple developer tools installed
+before proceeding with Pinax installation.
 
-Released tarball instructions
-=============================
 
-We have provided a script that will create a virtual environment for you.
-Once you have downloaded the release tarball, cd into the extracted directory.
-Let's create a virtual environment that you will install everything into::
+Installing Pinax
+================
+
+Pinax makes use of Python virtual environments (or virtualenvs) to isolate
+the various packages it uses from the rest of your system. Pinax comes with a
+script that will create the virtualenv for you and install Django and the
+various applications and libraries that make up Pinax.
+
+To run this script, extract the release bundle, cd into it and run::
+
+    $ python scripts/pinax-boot.py <path-to-virtual-env-to-create>
+
+This will set up the virtualenv and install everything.
+
+For example, if you wanted to create your environment in a directory parallel
+to where you extracted the bundle you could run::
 
     $ python scripts/pinax-boot.py ../pinax-env
-    $ cd ../
-    $ source ./pinax-env/bin/activate
-    (pinax-env)$
 
-Note that we have told you to create the new environment in the directory
-above the tarball directory. We encourage you create the environment anywhere
-you like.
+If you use virtualenvwrapper (which we recommend), this would become::
+
+    $ python scripts/pinax-boot.py $WORKON_HOME/pinax-env
 
-If you use virtualenvwrapper (we highly encourage you do), you can easily
-replace ../ with your WORKON_HOME. This gives you regular access to workon
-to activate your environment.
 
-You can skip the "Development instructions" section and begin reading the
-"Common to both approaches" section.
+Activating the virtualenv
+=========================
 
-Development instructions
-========================
+Any time you work on a project involving Pinax, you will want to activate
+the virtualenv.
 
-Download the latest pinax-boot.py script (you can put this anywhere, we will
-assume current working directory)::
+This is done with::
 
-    $ curl -O http://github.com/pinax/pinax/raw/master/scripts/pinax-boot.py
+    $ source <path-to-virtual-env-created>/bin/activate
 
-Create a virtual environment with the downloaded script::
+or, in our example above using ../pinax-env::
 
-    $ python pinax-boot.py --development ./pinax-env
-    $ source ./pinax-env/bin/activate
-    (pinax-env)$
+    $ source ../pinax-env/bin/activate
 
-The last step to pull down the external apps and libraries. To do this run::
+On Windows you would run::
 
-    (pinax-env)$ cd ./pinax-env/
-    (pinax-env)$ pip install --requirement src/pinax/requirements/external_apps.txt
+    $ ..\pinax-env\Scripts\activate.bat
 
-Common to both approaches
-=========================
+With virtualenvwrapper, this becomes::
 
-Your next step is to create a Pinax project. Let's first check what is
-available::
+    $ workon pinax-env
+
+which you can run from anywhere on your filesystem.
+
+Note that you will develop your Pinax-based project in a directory outside
+your virtualenv. As long as the virtualenv is active, your project will have
+access to all of the apps and libraries Pinax provides.
+
+
+Starting a new Pinax project
+============================
+
+The recommended way to start a new Pinax-based project is to clone one of the
+existing projects. This is done via the ``pinax-admin clone_project``
+command which you can run once you are in your Pinax virtual-env.
+
+You can get a list of available projects with::
 
     (pinax-env)$ pinax-admin clone_project -l
 
-This will show you a list of project that you can base your new project off
-of. For the purpose of testing Pinax, let's start with the social_project::
+This will show you a list of projects that you can base your new project on.
+
+Just as quick demonstration, let's start with the social_project. cd into the
+directory you'd like to create your new project in and run::
 
     (pinax-env)$ pinax-admin clone_project social_project mysite
 
@@ -75,4 +91,4 @@ directory. Lastly, let's get it running::
     (pinax-env)$ python manage.py runserver
 
 Point your browser at http://localhost:8000/ and you should see the Pinax
-default homepage!
+default homepage!

docs/install.txt

@@ -1,127 +1,89 @@
 Installation
 ============
 
-We have two different approaches to installing Pinax. The best approach is to
-download our stable release and follow the :ref:`install-released-tarball-instructions`.
-The benefit to this approach is that it requires absolutely no Internet
-connection once you have downloaded the tarball.
+This covers installation from a release bundle. For information on installing
+a development version, see http://pinaxproject.com/docs/dev/contributing.html.
 
-The alternative approach is to start from the development version. You can
-take this approach by following the :ref:`install-development-instructions`. This means
-you will be working with the bleeding edge of our code. We can not guarantee
-any stability.
+The release bundle has almost everything you need to get Pinax up and running.
+The only things not included are `Python`_ itself, the `Python Imaging Library`_
+(PIL) and a database such as SQLite (which is included in Python 2.5+).
 
-Alternatively, if you prefer or use `Buildout`_ see the
-:ref:`buildout instructions <ref-buildout>` for details.
-
-.. _install-released-tarball-instructions:
+For more information on installing PIL, see :ref:`ref-pil`.
 
 .. note::
 
-    If you are on OS X be sure you have the Apple developer tools installed.
-
-Released tarball instructions
------------------------------
+    If you are on Mac OS X, make sure you have the Apple developer tools
+    installed before proceeding with Pinax installation.
 
-We have provided a script that will create a virtual environment for you.
-Once you have downloaded the release tarball, cd into the extracted directory.
-Let's create a virtual environment that you will install everything into::
-
-    $ python scripts/pinax-boot.py ../pinax-env
-    $ cd ../
-    $ source ./pinax-env/bin/activate
-    (pinax-env)$
 
-Note that we have told you to create the new environment in the directory
-above the tarball directory. We encourage you create the environment anywhere
-you like.
+Installing Pinax
+----------------
 
-If you use `virtualenvwrapper`_ (we highly encourage you do), you can easily
-replace ``../`` with your ``WORKON_HOME``. This gives you regular access to
-``workon`` to activate your environment.
+Pinax makes use of Python virtual environments (or virtualenvs) to isolate
+the various packages it uses from the rest of your system. Pinax comes with a
+script that will create the virtualenv for you and install Django and the
+various applications and libraries that make up Pinax.
 
-You can skip the :ref:`install-development-instructions` section and begin
-reading the :ref:`install-common-to-both-approaches` section.
+To run this script, extract the release bundle, cd into it and run::
 
-.. _install-development-instructions:
-
-Development instructions
-------------------------
-
-.. note::
+    $ python scripts/pinax-boot.py <path-to-virtual-env-to-create>
 
-    These instructions are for the **developement** version of Pinax. We do
-    not guarantee it will actually work. It is possible dependancies will fail
-    to install or the master branch is unstable. Consider this your warning,
-    but if you do proceed and find issues, please report them at
-    http://code.pinaxproject.com.
+This will set up the virtualenv and install everything.
 
-Before installing the development version make sure you have the following:
+For example, if you wanted to create your environment in a directory parallel
+to where you extracted the bundle you could run::
 
-* `Git`_
-* `Subversion`_
+    $ python scripts/pinax-boot.py ../pinax-env
 
-These may not always be needed, but as fixes are made in external applications
-we may need to switch to their development versions. We try our best to avoid
-this. We abolutely require Git because it is our versioning control system of
-choice.
+If you use virtualenvwrapper_ (which we recommend), this would become::
 
-Download the latest pinax-boot.py script (you can put this anywhere, we will
-assume current working directory)::
+    $ python scripts/pinax-boot.py $WORKON_HOME/pinax-env
 
-    $ curl -O http://github.com/pinax/pinax/raw/master/scripts/pinax-boot.py
 
-Create a virtual environment with the downloaded script::
+Activating the virtualenv
+-------------------------
 
-    $ python pinax-boot.py --development ./pinax-env
-    $ source ./pinax-env/bin/activate
-    (pinax-env)$
+Any time you work on a project involving Pinax, you will want to activate
+the virtualenv.
 
-The last step deals with the external apps and libraries you want to use
-while developing your project. To do this choose **one** of these options:
+This is done with::
 
-* *All* dependencies (external_apps and libs) used in all sample projects::
+    $ source <path-to-virtual-env-created>/bin/activate
 
-    (pinax-env)$ cd pinax-env/
-    (pinax-env)$ pip install --requirement src/pinax/requirements/external_apps.txt
+or, in our example above using ``../pinax-env``::
 
-* *Only* the dependencies of one of the sample projects, e.g. the social_project::
+    $ source ../pinax-env/bin/activate
 
-    (pinax-env)$ cd pinax-env/src/pinax/projects/
-    (pinax-env)$ pip install --requirement social_project/requirements.txt
+On Windows you would run::
 
-.. _install-common-to-both-approaches:
+    $ ..\pinax-env\Scripts\activate.bat
 
-Common to both approaches
--------------------------
+With virtualenvwrapper, this becomes::
 
-A note about PIL
-~~~~~~~~~~~~~~~~
+    $ workon pinax-env
 
-To be able to run the ``social_project`` or any photo support provided with
-Pinax you will need the `Python Imaging Library`_ (aka PIL). We don't install
-this for you because its installation will vary and requires compilation.
-First, check with your OS package manager (if applicable) to see if it can
-provide PIL for you. Windows users can simply use the binaries provided on the
-PIL website.
+which you can run from anywhere on your filesystem.
 
-This command has worked for some users; it installed a tweaked version::
+Note that you will develop your Pinax-based project in a directory outside
+your virtualenv. As long as the virtualenv is active, your project will have
+access to all of the apps and libraries Pinax provides.
 
-    (pinax-env)$ pip install http://dist.repoze.org/PIL-1.1.6.tar.gz
 
-Of course you'll need a C compiler `libjpeg`_ and `libz`_ libraries upon which
-PIL depends.
+Starting a new Pinax project
+----------------------------
 
-Creating a project
-~~~~~~~~~~~~~~~~~~
+The recommended way to start a new Pinax-based project is to clone one of the
+existing projects. This is done via the ``pinax-admin clone_project``
+command which you can run once you are in your Pinax virtual-env.
 
-Your next step is to create a Pinax project. Let's first check what is
-available::
+You can get a list of available projects with::
 
     (pinax-env)$ pinax-admin clone_project -l
 
-This will show you a list of project that you can base your new project off
-of. For the purpose of testing Pinax, let's start with the social_project::
+This will show you a list of projects that you can base your new project on.
+
+Just as quick demonstration, let's start with the social_project. cd into the
+directory you'd like to create your new project in and run::
 
     (pinax-env)$ pinax-admin clone_project social_project mysite
 
@@ -138,19 +100,13 @@ default homepage!
 Note that mail and some notifications are queued rather than delivered
 immediately. See :ref:`ref-sending-mail-and-notices` for details.
 
-
 What's next?
 ------------
 
 Look at our :doc:`customization <customization>` documentation to learn how you
 might customize your cloned project. If you are ready to deploy your project
 check out the :doc:`deployment <deployment>` documentation.
 
-
-.. _`virtualenvwrapper`: http://www.doughellmann.com/projects/virtualenvwrapper/
-.. _`Git`: http://git-scm.com/
-.. _`Subversion`: http://subversion.tigris.org/
+.. _Python: http://python.org
 .. _`Python Imaging Library`: http://www.pythonware.com/products/pil/
-.. _`libjpeg`: http://freshmeat.net/projects/libjpeg/
-.. _`libz`: http://www.zlib.net/
-.. _`Buildout`: http://pypi.python.org/pypi/zc.buildout
+.. _`virtualenvwrapper`: http://www.doughellmann.com/projects/virtualenvwrapper/

docs/pil.txt

@@ -1,3 +1,5 @@
+.. _ref-pil:
+
 Installing PIL
 ==============