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