Permalink
Browse files

Updated INSTALL and install documentation to be released oriented

  • Loading branch information...
jtauber authored and brosner committed Sep 3, 2009
1 parent e23a640 commit f7474a9ccd3b89a9c0c55643ac1c1a999f606c47
Showing with 113 additions and 139 deletions.
  1. +61 −45 INSTALL
  2. +50 −94 docs/install.txt
  3. +2 −0 docs/pil.txt
View
106 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!
View
@@ -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/
View
@@ -1,3 +1,5 @@
+.. _ref-pil:
+
Installing PIL
==============

0 comments on commit f7474a9

Please sign in to comment.