Readme update

README.rst

@@ -4,4 +4,117 @@ Slack backup
 .. image:: https://travis-ci.org/gryf/slack-backup.svg?branch=master
     :target: https://travis-ci.org/gryf/slack-backup
 
-Make copy of slack conversations.
+This simple project which aim is to collect conversations from Slack using its
+API and optionally user account information, and provides convenient way to
+represent as a log.
+
+Requirements
+------------
+
+This project is written in Python 2.7, and 3.4+, although version 2.7, which
+should work, wasn't tested as extensively as it should be.
+
+Other than that, required packages are as follows:
+
+- slackclient 1.0.2
+- SQLAlchemy 1.0.10
+
+Installation
+------------
+
+You can install it using ``pip install slack-backup`` command. Recommended way
+is to create virtualenv, like so:
+
+.. code:: shell-session
+
+   user@localhost $ virtualenv -p python3 myenv
+   Running virtualenv with interpreter /usr/bin/python3
+   Using base prefix '/usr'
+   New python executable in foobar/bin/python3
+   Also creating executable in foobar/bin/python
+   Installing setuptools, pip, wheel...done.
+   user@localhost $ . myenv/bin/activate
+   (myenv)user@localhost $ pip install slack-backup
+
+You can also get this repository and install from it, like:
+
+.. code:: shell-session
+
+   user@localhost ~ $ virtualenv -p python3 myenv
+   Running virtualenv with interpreter /usr/bin/python3
+   Using base prefix '/usr'
+   New python executable in foobar/bin/python3
+   Also creating executable in foobar/bin/python
+   Installing setuptools, pip, wheel...done.
+   user@localhost $ . myenv/bin/activate
+   (myenv)user@localhost ~ $ cd myenv
+   (myenv)user@localhost ~/myenv $ git clone https://github.com/gryf/slack-backup
+   (myenv)user@localhost ~/myenv $ cd slack-backup
+   (myenv)user@localhost ~/myenv/slack-backup $ pip install .
+
+Usage
+-----
+
+There is a commandline tool called `slack-backup`, which typical use would get
+to gather the data and generate logs. Using example from above, here is a
+typical session:
+
+.. code:: shell-session
+
+   (myenv)user@localhost ~/myenv/slack-backup $ mkdir ~/mylogs && cd ~/mylogs
+   (myenv)user@localhost ~/mylogs $ slack-backup fetch \
+   --token xxxx-1111111111-222222222222-333333333333-r4nd0ms7uff \
+   --user some@email.address.org --password secret --team myteam \
+   -qqq -d mydatabase.sqlite
+
+where:
+
+* ``--token`` is generated on `Slack side token`_ for interaction with the API.
+  It's required.
+* ``--user`` is your slack account username…
+* ``--password`` …and password. Those two are needed if you care about files
+  posted on the channels, which are hosted on Slack servers. They can be
+  skipped, if you don't care about such files. Avatars still be downloaded
+  though. External resources will not be downloaded - they have URL anyway.
+* ``--team`` team name. It is the part of the URL for your slack team; in other
+  words in URL like `http://foobar.slack.com` *foobar* is the team name.
+* ``-q`` (or ``--quiet``) will suppress any messages from program. In contrary
+  there can be used ``--verbose`` to increase verbosity. Using this option
+  several times (up to three, above the number will have no effect) will amplify
+  effectiveness of either be quite or be verbose behaviour.
+* ``-d`` or ``--database`` is the file path for database (which for now at least
+  is an sqlite database file). It can be omitted - in-memory db would be
+  created, but you'll (obviously) lost all the records. Besides the db file,
+  assets directory might be created for downloadable items.
+
+During DB creation, all available messages are stored in the database. On the
+next run, ``fetch`` would only take those records, which are older from
+currently oldest in DB. So that it will only fetch a subset of the overall of
+the messages. As for the channels and users - complete information will be
+downloaded every time ``fetch`` command would be used.
+
+Next, to generate a log files:
+
+.. code:: shell-session
+
+   (myenv)user@localhost ~/mylogs $ slack-backup generate \
+   -v -d mydatabase.sqlite --format text -o logs
+
+where:
+
+* ``--format`` is the desired format of the logs. For now only ``text`` format
+  of the logs is supported (IRC style format). Format ``none`` will produce
+  nothing.
+* ``-o`` or ``--output`` is the destination directory, where logs and possible
+  assets will land.
+
+The rest of the options (``-d`` and ``-v``) have same meaning as in ``fetch``
+command.
+
+
+License
+-------
+
+This work is licensed on 3-clause BSD license. See LICENSE file for details.
+
+.. _Slack side token: https://api.slack.com/docs/oauth-test-tokens