update README
[rainbowstream.git] / README.rst
CommitLineData
3108149e 1Rainbow Stream\r
2--------------\r
3\r
d7fbaba9
O
4.. image:: http://img.shields.io/pypi/dm/rainbowstream.svg?style=flat\r
5 :target: https://pypi.python.org/pypi/rainbowstream\r
3216f3f4 6\r
d7fbaba9
O
7.. image:: http://img.shields.io/pypi/v/rainbowstream.svg?style=flat\r
8 :target: https://pypi.python.org/pypi/rainbowstream\r
c96321cc 9\r
3108149e 10Terminal-based Twitter Client. Realtime tweetstream, compose, search ,\r
11favorite … and much more fun directly from terminal.\r
12\r
80fa0f3a 13This package is built on the top of `Python Twitter Tool`_ and `Twitter API`_,\r
687567eb 14can run on Python 2.7.x and 3.x .\r
091aaddc 15\r
3108149e 16\r
456019d6 17Showcase\r
b13c6a0d 18--------\r
456019d6 19\r
bd48f980 20.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/rs.gif\r
99087831 21 :alt: gif\r
997c0570 22\r
3108149e 23Install\r
24-------\r
25\r
45e6bb0d
O
26The quick way\r
27^^^^^^^^^^^^^\r
28\r
8e004f8d 29You will need Python and pip (2.7.x or 3.x).\r
3108149e 30\r
31.. code:: bash\r
32\r
fd9cd791 33 sudo pip install rainbowstream\r
8e004f8d 34 # Python 3 users: sudo pip3 install rainbowstream\r
b84845b9 35\r
b84845b9 36\r
45e6bb0d
O
37The recommended way\r
38^^^^^^^^^^^^^^^^^^^\r
39\r
40Use `virtualenv`_\r
fd9cd791
O
41\r
42.. code:: bash\r
43\r
b84845b9 44 virtualenv venv\r
45e6bb0d
O
45 # Python 3 users : use -p to specify your Python 3 localtion as below\r
46 # virtualenv -p /usr/bin/python3 venv\r
47 source venv/bin/activate\r
3108149e 48 pip install rainbowstream\r
49\r
80fa0f3a
O
50Troubleshooting\r
51^^^^^^^^^^^^^^^\r
52\r
cfe34c93 53If you use Linux, you might need to install some packages if you haven't already. \r
c30d954c
O
54For debian-based distros, these can be installed with\r
55\r
56.. code:: bash\r
57\r
41c009e2 58 sudo apt-get install python-dev libjpeg libjpeg-dev libfreetype6 libfreetype6-dev zlib1g-dev\r
c30d954c
O
59\r
60Besides, Mac OSX Maverick with Xcode 5.1 has a well-known `clang unknown argument`_ problem with\r
80fa0f3a 61the ``Pillow`` package installation - a dependency of this app.\r
49c9d9b4 62If you are in this case, I recommend taking a look at `Issue #10`_ and let me know if this workaround doesn't work for you.\r
cfe34c93
O
63\r
64.. code:: bash\r
65\r
66 export ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future\r
cfe34c93 67\r
49c9d9b4 68If installation in *the quick way* doesn't work:\r
69\r
70- `sudo pip uninstall rainbowstream`\r
71- use the *virtualenv way* above\r
72- `create an issue`_ and provide:\r
cfe34c93 73\r
49c9d9b4 74 + Your OS\r
75 + Your Python version\r
45e6bb0d 76\r
3108149e 77Usage\r
78-----\r
79\r
80The stream\r
81^^^^^^^^^^\r
82\r
83Just type\r
84\r
85.. code:: bash\r
86\r
9f37426f 87 rainbowstream\r
3108149e 88\r
89and see your stream.\r
90\r
3216f3f4
O
91I shipped a feature which can display **tweet's images directly on terminal**.\r
92You can try it with:\r
4373c17c
O
93\r
94.. code:: bash\r
95\r
9f37426f 96 rainbowstream -iot # Or rainbowstream --image-on-term\r
4373c17c 97\r
99037620
O
98You also can change the config key ``IMAGE_ON_TERM`` to ``True`` inside the app \r
99to enable above feature, \r
100change ``IMAGE_SHIFT`` to set image's margin (relative to your terminal's width) \r
101or ``IMAGE_MAX_HEIGHT`` to control max height of every image.\r
102(see `config management`_ section).\r
89d0f21f 103\r
3108149e 104In the first time you will be asked for authorization of Rainbow Stream\r
105app at Twitter. Just click the “Authorize access” button and paste PIN\r
3216f3f4 106number to the terminal, the rainbow will start.\r
3108149e 107\r
108The interactive mode\r
9348f8ed 109^^^^^^^^^^^^^^^^^^^^\r
3108149e 110\r
111While your personal stream is continued, you are also ready to tweet,\r
112search, reply, retweet… directly from console. Simply type “h” and hit\r
f5677fb1 113the Enter key to see the help.\r
3108149e 114\r
115Input is in interactive mode. It means that you can use arrow key to\r
116move up and down history, tab-autocomplete or 2 tab to view available\r
f5677fb1 117suggestion. Input history from previous run is available as well.\r
3108149e 118\r
b913cd75 119Available commands are listed in `Read The Docs`_.\r
3108149e 120\r
b913cd75 121Theme customization\r
9348f8ed 122^^^^^^^^^^^^^^^^^^^\r
b913cd75 123\r
06302419 124Rainbow Stream is shipped with some default themes.\r
b913cd75
O
125You can either change theme by ``theme`` command or create your favorite one.\r
126\r
547283bf 127Theme’s screenshot:\r
19d6c002 128\r
06302419
O
129- Monokai\r
130\r
547283bf
O
131.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Monokai.png\r
132 :alt: monokai\r
19d6c002 133\r
06302419
O
134- Solarized\r
135\r
547283bf
O
136.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/Solarized.png\r
137 :alt: solarized\r
138\r
98258022
O
139- Tomorrow Night\r
140\r
141.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/TomorrowNight.png\r
142 :alt: tomorrownight\r
143\r
144- Larapaste\r
145\r
146.. figure:: https://raw.githubusercontent.com/DTVD/rainbowstream/master/screenshot/themes/larapaste.png\r
147 :alt: larapaste\r
148\r
b913cd75 149For detaile information, see `theme usage and customization`_.\r
3108149e 150\r
9348f8ed 151\r
050c4214 152Bug and feature requests\r
36e1924e 153------------------------\r
3108149e 154\r
b84845b9 155Found a bug or a feature request ?\r
3216f3f4 156Please `create an issue`_ or contact me at `@dtvd88`_\r
3108149e 157\r
2d341029
O
158Development\r
159-----------\r
160\r
161If you want to build a runnable version yourself, follow these simple\r
162steps\r
163\r
164- `Create your own Twitter Application`_\r
165- Get your Twitter application’s API key and secret\r
a80d4179 166- Fork this repo and clone in your system.\r
b145ada0 167- Create a file ``consumer.py`` in `rainbowstream`_ folder with\r
2d341029
O
168 following content\r
169\r
170 .. code:: python\r
171\r
172 # Consumer information\r
173 CONSUMER_KEY = 'APIKey' # Your Twitter application's API key\r
174 CONSUMER_SECRET = 'APISecret' # Your Twitter application's API secret\r
175\r
176- Use pip to install in local\r
177\r
178 .. code:: bash\r
179\r
a80d4179 180 # cd to directory which contains setup.py (cloned directory)\r
2d341029
O
181 virtualenv venv # Python3 users: use -p to specify python3\r
182 source venv/bin/activate\r
183 pip install -e .\r
a80d4179
O
184 which rainbowstream # /this-directory/venv/bin/rainbowstream\r
185 pip list | grep rainbowstream # rainbowstream (0.x.x, /this-directory)\r
186 # Remove ~/.rainbow_oauth if exists\r
2d341029
O
187 rainbowstream # local version of rainbowstream\r
188\r
189\r
050c4214 190Contributing\r
36e1924e 191------------\r
050c4214
O
192I appreciate any help and support. Feel free to `fork`_ and `create a pull request`_.\r
193You will be listed as contributor.\r
194\r
3108149e 195License\r
196-------\r
197\r
198Rainbow Stream are released under an MIT License. See LICENSE.txt for\r
199details\r
200\r
201\r
202.. _Python Twitter Tool: http://mike.verdone.ca/twitter/\r
bade45d4 203.. _Twitter API: https://dev.twitter.com/docs/api/1.1\r
3108149e 204.. _create an issue: https://github.com/DTVD/rainbowstream/issues/new\r
3216f3f4 205.. _@dtvd88: https://twitter.com/dtvd88\r
050c4214
O
206.. _fork: https://github.com/DTVD/rainbowstream/fork\r
207.. _create a pull request: https://github.com/DTVD/rainbowstream/compare/\r
670e8049 208.. _Read The Docs: http://rainbowstream.readthedocs.org/en/latest/\r
b52327dc 209.. _config guide: https://github.com/DTVD/rainbowstream/blob/master/theme.md\r
b913cd75 210.. _theme usage and customization: https://github.com/DTVD/rainbowstream/blob/master/theme.md\r
2d341029 211.. _Create your own Twitter Application: https://apps.twitter.com/app/new\r
b145ada0 212.. _rainbowstream: https://github.com/DTVD/rainbowstream/tree/master/rainbowstream\r
45e6bb0d 213.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/\r
98f3deaa 214.. _config management: http://rainbowstream.readthedocs.org/en/latest/#config-explanation\r
3ac213c1
O
215.. _clang unknown argument: http://kaspermunck.github.io/2014/03/fixing-clang-error/\r
216.. _Issue #10: https://github.com/DTVD/rainbowstream/issues/10\r