veekun_pokedex/doc/installing.rst

Installing the pokedex library
==============================

Quick startup with Ubuntu/Debian-like systems
---------------------------------------------

Run the following from an empty directory::

    $ sudo apt-get install git python python-pip python-sqlalchemy
    $ git clone git://github.com/veekun/pokedex.git
    $ pip install -e pokedex
    $ source env/bin/activate
    (env)$ pokedex setup -v
    (env)$ pokedex lookup eevee

If it all goes smoothly, you can now use ``env/bin/pokedex``, the command-line
tool, and ``env/bin/python``, a Python interpreter configured to use the
pokedex library.

That is all you need. Feel free to skip the rest of this chapter if you're not
interested in the details.

Prerequisites
-------------

Linux
^^^^^

Ubuntu/Debian users should run the following::

    $ sudo apt-get install git python python-pip

With other Linuxes, install the packages for git, python (2.6 or 2.7,
*not* 3.x), and python-pip.

If you succeeded, skip the Detailed instructions.

Detailed instructions
^^^^^^^^^^^^^^^^^^^^^

You should know what a command line is and how to work with it.
The here we assume you're using Linux [#]_, if that's not the case, make
sure you have enough computer knowledge to translate the instructions to your
operating system.

Pokedex is distributed via Git_. So, get Git.

You will also need Python_ 2; the language pokedex is written in. Be sure to get
version **2.6** or **2.7**. Pokedex does not work with Python 3.x yet, and it
most likely won't work with 2.5 or earlier.

Next, get pip_, a tool to install Python packages. Experts can use another
tool, of course.

Make sure git and pip are on your path.

Optionally you can install SQLAlchemy_, `Python markdown`_, Whoosh_,
or construct_. If you don't, pip will atuomatically download and install a copy
for you, but some are pretty big so you might want to install it system-wide.
(Unfortunately, many distros have outdated versions of these libraries, so pip
will install pokedex's own copy anyway.)

Getting and installing pokedex
------------------------------

Run the following from an empty directory::

    $ git clone git://github.com/veekun/pokedex.git
    $ pip install -e pokedex

This will give you two directories: pokedex (containing the source code and
data), and env (a virtualenv_).

In env/bin, there are three interesting files:

* pokedex: The pokedex program
* python: A copy of Python that knows about pokedex and its prerequisites.
* activate: Typing ``source env/bin/activate`` in a shell will put
  pokedex and our bin/python on the $PATH, and generally set things up to work
  with them. Your prompt will change to let you know of this. You can end such
  a session by typing ``deactivate``.

This documentation will assume that you've activated the virtualenv, so
``pokedex`` means ``env/bin/pokedex``.

Advanced
^^^^^^^^

You can of course install into an existing virtualenv, by either using its pip
and leaving out the ``-E env``, or running the setup script directly::

    (anotherenv)$ cd pokedex
    (anotherenv)pokedex$ python setup.py develop

It is also possible to install pokedex system-wide. There are problems with
that. Don't do it. The only time you need ``sudo`` is for getting the
prerequisites.

Loading the database
--------------------

Before you can do anything useful with pokedex, you need to load the database::

    $ pokedex setup -v

This will load the data into a default SQLite database and create a default
Whoosh index.

Advanced
^^^^^^^^

If you want to use another database, make sure you have the corresponding
`SQLAlchemy engine`_ for it and either use the ``-e`` switch, (e.g.
``-e postgresql://@/pokedex``), or set the ``POKEDEX_DB_ENGINE`` environment
variable.

To use another lookup index directory, specify it with ``-i`` or the
``POKEDEX_INDEX_DIR`` variable.

Make sure you always use the same options whenever you use pokedex.

If you're confused about what pokedex thinks its settings are, check
``pokedex status``.

See ``pokedex help`` for even more options.

All done
--------

To verify that all went smoothly, check that the pokedex tool finds your
favorite pokémon::

    $ pokedex lookup eevee

Yes, that was a bit anti-climatic. The command-line tool doesn't do much,
currently.






.. _Git: http://git-scm.com/
.. _Python: http://www.python.org/
.. _pip: http://pypi.python.org/pypi/pip
.. _SQLAlchemy: www.sqlalchemy.org/
.. _`Python markdown`: http://www.freewisdom.org/projects/python-markdown/
.. _Whoosh: http://whoosh.ca/
.. _construct: pypi.python.org/pypi/construct
.. _virtualenv: http://www.virtualenv.org/en/latest/
.. _`SQLAlchemy engine`: http://www.sqlalchemy.org/docs/core/engines.html

.. rubric:: Footnotes
.. [#] If you write instructions for another OS, well be happy to include them
    here. The reason your OS is not listed here is because the author doesn't
    use it, so naturally he can't write instructions for it.