<commit_before>Installation
============
 
The sample projects in Pinax depend on a lot of external apps and libraries.
Since we moved to distutils/setuptools we are able to manage those
dependencies by using useful tools `virtualenv`_, `pip`_ and `buildout`_.
 
One exciting feature of pip for example is the ability to install Python
packages like the external apps directly from various version control systems.
The development version of Pinax relies on some apps that are hosted that way.
So please make sure you have the latest versions installed of: Subversion_,
Git_, Mercurial_ and Bazaar_. If you prefer to use buildout you can use the
provided buildout.cfg, which uses `gp.recipe.pip`_ internally.
 
To make it easier to start with developing your own Pinax based project we
provide a `virtualenv bootstrap script`_. It creates a virtualenv with the
necessary Pinax Git clone and installs pip_ and Django_ inside the
environment. This allows you to keep your whole project inside one directory
and doesn't spoil the global site-packages directory with all the dependencies.
 
First download the virtualenv bootstrap script (Linux)::
 
    curl -o pinax-boot.py http://github.com/pinax/pinax/raw/master/scripts/pinax-boot.py
 
or open ``http://github.com/pinax/pinax/raw/master/scripts/pinax-boot.py`` in
your browser and save it on your hard disk.
 
Then run the script, e.g. to create a environment called ``pinax-env``::
 
    python pinax-boot.py pinax-env
 
After that you need to `activate the new environment`_ so your shell session
knows which Python interpreter and site-packages directory to use. If you use
bash you can simply run this in the environment root directory (make sure
you change your current working directory first, e.g. ``cd pinax-env``)::
 
    source bin/activate
 
You are now able to install the required external apps and libraries by either
using pip or buildout, whatever you prefer.
 
The one exception is the `Python Imaging Library`_ (PIL)
which you will have to provide yourself if you want photo support.

From within your activated virtual environment, these command have
worked for some users; it installed tweaked versions::

  (venv)$ pip install  http://dist.repoze.org/PIL-1.1.6.tar.gz

or::

  (venv)$  easy_install -i http://dist.serverzen.com/pypi/simple PILwoTk

Of course you'll need a C compiler, and `libjpeg`_ `libz`_ libraries
upon which PIL depends.

On GNU/Linux you may be able to RPM or yum install libjpeg-devel to
automate this. If not, compiling from source isn't that hard.

.. note::
    
    Some of the external apps are still link hosted with Google Code. It is
    common to see::
    
        Fetching external item into 'apps/external_apps/django_extensions'
        svn: PROPFIND request failed on '/svn/trunk/django_extensions'
        svn: PROPFIND of '/svn/trunk/django_extensions': 502 Bad Gateway (http://django-command-extensions.googlecode.com)
    
    You should be able to ignore it and try the installation, checkout or
    update again.
 
Using ``pip``
-------------
 
``pip`` allows you to install the required Python packages by passing a simple
text file containing a list of requirement strings, e.g. django-wikiapp==0.1.2.
Please don't hesitate to read about the requirement files in
`pip's documentation`_. We currently provide two requirement files:
 
* ``requirements/libs.txt`` - Libraries and non-Django packages
* ``requirements/external_apps.txt`` - External reusable Django apps
 
Note that the latter automatically includes the libraries. You should think of
it as a starting point for your own requirement files. For example here's
how you start the installation of every requirement::
 
    pip install --requirement src/pinax/requirements/external_apps.txt
 
We will however provide `requirements files`_ for each sample project soon so
you don't have to install the apps and libraries used in all Pinax sample
projects.
 
In case you want to update the development version of Pinax you have to update
both Pinax and the apps separately. The Pinax code is located in the
directory ``src/pinax`` inside your virtualenv (e.g. ``pinax-env``). You can
update it by first changing your working directory with
``cd pinax-env/src/pinax`` and then running::
 
    git pull
 
To update the apps and libraries run again inside the environment root
directory::
 
    pip install --requirement src/pinax/requirements/external_apps.txt
 
Note that if you want to use another external app or external library,
you don't need to use the `requirement file we provide`_. Don't hesitate to
write your own or install it directly with pip inside your environment.
 
Using ``buildout``
------------------
 
``buildout`` enables you to go a bit further in the way you handle
requirements by abstracting the different deployment scenarios with
so-called `recipes`_. Pinax for example uses a `pip recipe`_ to make sure
every requirement is installed properly. But you can easily integrate it with
your current buildouts.
 
To get started with buildout you first need to install buildout in the
virtualenv we created with the virtualenv bootstrap script::
 
    pip install zc.buildout
 
After that you'll have a new executable inside your ``bin`` (Linux) or
``Script`` directory (Windows) which you'll use with a buildout config file
we provide.
 
This file needs to be downloaded from the Pinax repository and saved in the
virtualenv root directory. So please make sure you are in the directory that
contains the following directories (among others): ``bin``, ``build`` and
``src`` and run (on Linux)::
 
    curl -o buildout.cfg http://github.com/pinax/pinax/raw/master/buildout.cfg
 
or open ``http://github.com/pinax/pinax/raw/master/buildout.cfg`` in
your browser and save it on your hard disk in the virtualenv root directory.
 
Then all you need to do is to run the buildout command inside the virtualenv
root directory. You can update the buildout and the packages it contains
by running buildout again.
 
What's next?
------------
 
Once the installation is complete, you should be able to cd into
``src/pinax/pinax/projects/social_project/`` or
``src/pinax/pinax/projects/basic_project/`` and run
``./manage.py syncdb`` and ``./manage.py runserver`` to get running
immediately.
 
These are just sample projects, however. You will likely want to create your
own project and :doc:`customize <customization>` it.
 

 
Directory Structure
-------------------

======================= ====================================================
``docs/``               documentation (using rst and sphinx; in progress)
``pinax/``              pinax package itself
``pinax/apps/``           re-usable apps that aren't yet externalized
``pinax/core/``           core management command for project creation
``pinax/fixtures/``       test fixtures (in progress)
``pinax/media/``          shared media (images, css, javscript)
``pinax/projects/``       sample and starter projects
``pinax/templates/``      shared templates
``requirements/``       pip requirements files for externals apps and libs
``scripts/``            scripts for bootstrapping dev and building release
======================= ====================================================


There is some path manipulation in manage.py to get this all to work. You'll
need to do something similar in your wsgi or mod_python configuration. See
:doc:`deployment` for more details.
 
.. _`Python Imaging Library`: http://www.pythonware.com/products/pil/
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
.. _pip: http://pypi.python.org/pypi/pip
.. _activate the new environment: http://pypi.python.org/pypi/virtualenv#activate-script
.. _virtualenv bootstrap script: http://pypi.python.org/pypi/virtualenv#creating-your-own-bootstrap-scripts
.. _Subversion: http://subversion.tigris.org/
.. _Git: http://git-scm.com/
.. _Mercurial: http://www.selenic.com/mercurial/
.. _Bazaar: http://bazaar-vcs.org/
.. _requirements files: http://pip.openplans.org/requirement-format.html
.. _requirement file we provide: http://github.com/pinax/pinax/raw/master/requirements/external_apps.txt
.. _Django: http://www.djangoproject.com/
.. _buildout: http://pypi.python.org/pypi/zc.buildout
.. _gp.recipe.pip: http://pypi.python.org/pypi/gp.recipe.pip
.. _`pip's documentation`: http://pip.openplans.org/
.. _recipes: http://pypi.python.org/pypi/zc.buildout#id1
.. _`pip recipe`: http://pypi.python.org/pypi/gp.recipe.pip
.. _`libjpeg`: http://freshmeat.net/projects/libjpeg/
.. _`libz`: http://www.zlib.net/<commit_msg>Added a quick bit about the install documentation for released versions of Pinax.<commit_after>Installation
============

We are working on re-writing this page as a part of our next beta release.
Please see the `INSTALL`_ documentation for the best documentation of the
released version of Pinax.
 
The sample projects in Pinax depend on a lot of external apps and libraries.
Since we moved to distutils/setuptools we are able to manage those
dependencies by using useful tools `virtualenv`_, `pip`_ and `buildout`_.
 
One exciting feature of pip for example is the ability to install Python
packages like the external apps directly from various version control systems.
The development version of Pinax relies on some apps that are hosted that way.
So please make sure you have the latest versions installed of: Subversion_,
Git_, Mercurial_ and Bazaar_. If you prefer to use buildout you can use the
provided buildout.cfg, which uses `gp.recipe.pip`_ internally.
 
To make it easier to start with developing your own Pinax based project we
provide a `virtualenv bootstrap script`_. It creates a virtualenv with the
necessary Pinax Git clone and installs pip_ and Django_ inside the
environment. This allows you to keep your whole project inside one directory
and doesn't spoil the global site-packages directory with all the dependencies.
 
First download the virtualenv bootstrap script (Linux)::
 
    curl -o pinax-boot.py http://github.com/pinax/pinax/raw/master/scripts/pinax-boot.py
 
or open ``http://github.com/pinax/pinax/raw/master/scripts/pinax-boot.py`` in
your browser and save it on your hard disk.
 
Then run the script, e.g. to create a environment called ``pinax-env``::
 
    python pinax-boot.py pinax-env
 
After that you need to `activate the new environment`_ so your shell session
knows which Python interpreter and site-packages directory to use. If you use
bash you can simply run this in the environment root directory (make sure
you change your current working directory first, e.g. ``cd pinax-env``)::
 
    source bin/activate
 
You are now able to install the required external apps and libraries by either
using pip or buildout, whatever you prefer.
 
The one exception is the `Python Imaging Library`_ (PIL)
which you will have to provide yourself if you want photo support.

From within your activated virtual environment, these command have
worked for some users; it installed tweaked versions::

  (venv)$ pip install  http://dist.repoze.org/PIL-1.1.6.tar.gz

or::

  (venv)$  easy_install -i http://dist.serverzen.com/pypi/simple PILwoTk

Of course you'll need a C compiler, and `libjpeg`_ `libz`_ libraries
upon which PIL depends.

On GNU/Linux you may be able to RPM or yum install libjpeg-devel to
automate this. If not, compiling from source isn't that hard.

.. note::
    
    Some of the external apps are still link hosted with Google Code. It is
    common to see::
    
        Fetching external item into 'apps/external_apps/django_extensions'
        svn: PROPFIND request failed on '/svn/trunk/django_extensions'
        svn: PROPFIND of '/svn/trunk/django_extensions': 502 Bad Gateway (http://django-command-extensions.googlecode.com)
    
    You should be able to ignore it and try the installation, checkout or
    update again.
 
Using ``pip``
-------------
 
``pip`` allows you to install the required Python packages by passing a simple
text file containing a list of requirement strings, e.g. django-wikiapp==0.1.2.
Please don't hesitate to read about the requirement files in
`pip's documentation`_. We currently provide two requirement files:
 
* ``requirements/libs.txt`` - Libraries and non-Django packages
* ``requirements/external_apps.txt`` - External reusable Django apps
 
Note that the latter automatically includes the libraries. You should think of
it as a starting point for your own requirement files. For example here's
how you start the installation of every requirement::
 
    pip install --requirement src/pinax/requirements/external_apps.txt
 
We will however provide `requirements files`_ for each sample project soon so
you don't have to install the apps and libraries used in all Pinax sample
projects.
 
In case you want to update the development version of Pinax you have to update
both Pinax and the apps separately. The Pinax code is located in the
directory ``src/pinax`` inside your virtualenv (e.g. ``pinax-env``). You can
update it by first changing your working directory with
``cd pinax-env/src/pinax`` and then running::
 
    git pull
 
To update the apps and libraries run again inside the environment root
directory::
 
    pip install --requirement src/pinax/requirements/external_apps.txt
 
Note that if you want to use another external app or external library,
you don't need to use the `requirement file we provide`_. Don't hesitate to
write your own or install it directly with pip inside your environment.
 
Using ``buildout``
------------------
 
``buildout`` enables you to go a bit further in the way you handle
requirements by abstracting the different deployment scenarios with
so-called `recipes`_. Pinax for example uses a `pip recipe`_ to make sure
every requirement is installed properly. But you can easily integrate it with
your current buildouts.
 
To get started with buildout you first need to install buildout in the
virtualenv we created with the virtualenv bootstrap script::
 
    pip install zc.buildout
 
After that you'll have a new executable inside your ``bin`` (Linux) or
``Script`` directory (Windows) which you'll use with a buildout config file
we provide.
 
This file needs to be downloaded from the Pinax repository and saved in the
virtualenv root directory. So please make sure you are in the directory that
contains the following directories (among others): ``bin``, ``build`` and
``src`` and run (on Linux)::
 
    curl -o buildout.cfg http://github.com/pinax/pinax/raw/master/buildout.cfg
 
or open ``http://github.com/pinax/pinax/raw/master/buildout.cfg`` in
your browser and save it on your hard disk in the virtualenv root directory.
 
Then all you need to do is to run the buildout command inside the virtualenv
root directory. You can update the buildout and the packages it contains
by running buildout again.
 
What's next?
------------
 
Once the installation is complete, you should be able to cd into
``src/pinax/pinax/projects/social_project/`` or
``src/pinax/pinax/projects/basic_project/`` and run
``./manage.py syncdb`` and ``./manage.py runserver`` to get running
immediately.
 
These are just sample projects, however. You will likely want to create your
own project and :doc:`customize <customization>` it.
 

 
Directory Structure
-------------------

======================= ====================================================
``docs/``               documentation (using rst and sphinx; in progress)
``pinax/``              pinax package itself
``pinax/apps/``           re-usable apps that aren't yet externalized
``pinax/core/``           core management command for project creation
``pinax/fixtures/``       test fixtures (in progress)
``pinax/media/``          shared media (images, css, javscript)
``pinax/projects/``       sample and starter projects
``pinax/templates/``      shared templates
``requirements/``       pip requirements files for externals apps and libs
``scripts/``            scripts for bootstrapping dev and building release
======================= ====================================================


There is some path manipulation in manage.py to get this all to work. You'll
need to do something similar in your wsgi or mod_python configuration. See
:doc:`deployment` for more details.

.. _`INSTALL`: http://github.com/pinax/pinax/blob/master/INSTALL 
.. _`Python Imaging Library`: http://www.pythonware.com/products/pil/
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
.. _pip: http://pypi.python.org/pypi/pip
.. _activate the new environment: http://pypi.python.org/pypi/virtualenv#activate-script
.. _virtualenv bootstrap script: http://pypi.python.org/pypi/virtualenv#creating-your-own-bootstrap-scripts
.. _Subversion: http://subversion.tigris.org/
.. _Git: http://git-scm.com/
.. _Mercurial: http://www.selenic.com/mercurial/
.. _Bazaar: http://bazaar-vcs.org/
.. _requirements files: http://pip.openplans.org/requirement-format.html
.. _requirement file we provide: http://github.com/pinax/pinax/raw/master/requirements/external_apps.txt
.. _Django: http://www.djangoproject.com/
.. _buildout: http://pypi.python.org/pypi/zc.buildout
.. _gp.recipe.pip: http://pypi.python.org/pypi/gp.recipe.pip
.. _`pip's documentation`: http://pip.openplans.org/
.. _recipes: http://pypi.python.org/pypi/zc.buildout#id1
.. _`pip recipe`: http://pypi.python.org/pypi/gp.recipe.pip
.. _`libjpeg`: http://freshmeat.net/projects/libjpeg/
.. _`libz`: http://www.zlib.net/
{'fraction_non_alphanumeric': 0.10757384208711643, 'fraction_numerical': 0.0011492931846914147, 'mean_word_length': 3.8761557859344355, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2591331', 'n_tokens_mistral': 4996, 'n_tokens_neox': 4647, 'n_words': 2085}