Skip to content

Commit b7648dc

Browse files
ingwinluingwinlu
committed
start documentation effort
1 parent ca0a611 commit b7648dc

13 files changed

Lines changed: 286 additions & 19 deletions

File tree

‎docs/api.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
API
2+
===
3+
4+
.. warning::
5+
6+
This documentation is currently a work in progress and is still rough
7+
around the edges. Not finding what you are looking for? Please open an
8+
issue describing your troubles on `python-twitch's github page`_!
9+
10+
11+
.. automodule:: twitch.api.v3
12+
:members:
13+
14+
15+
scraper
16+
-------
17+
18+
.. automodule:: twitch.scraper
19+
20+
.. Links
21+
22+
.. _twitch: http://www.twitch.tv/
23+
.. _Python: http://www.python.org/
24+
.. _`python-twitch's github page`: https://github.com/ingwinlu/python-twitch

‎docs/conf.py‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@
2121
# If extensions (or modules to document with autodoc) are in another directory,
2222
# add these directories to sys.path here. If the directory is relative to the
2323
# documentation root, use os.path.abspath to make it absolute, like shown here.
24-
#sys.path.insert(0, os.path.abspath('.'))
24+
25+
sys.path.insert(0, os.path.abspath('.'))
2526

2627
# -- General configuration ------------------------------------------------
2728

@@ -33,6 +34,8 @@
3334
# ones.
3435
extensions = [
3536
'sphinx.ext.autodoc',
37+
'sphinx.ext.ifconfig',
38+
'sphinx.ext.extlinks',
3639
'sphinx.ext.doctest',
3740
]
3841

@@ -58,11 +61,15 @@
5861
# The version info for the project you're documenting, acts as replacement for
5962
# |version| and |release|, also used in various other places throughout the
6063
# built documents.
61-
#
62-
# The short X.Y version.
63-
version = '1.2.0'
64-
# The full version, including alpha/beta/rc tags.
65-
release = '1.2.0'
64+
import pkg_resources
65+
try:
66+
release = pkg_resources.get_distribution(project).version
67+
except pkg_resources.DistributionNotFound:
68+
print("twitch distribution not found, needed to build the docs")
69+
sys.exit(1)
70+
del pkg_resources
71+
72+
version = '.'.join(release.split('.')[:2])
6673

6774
# The language for content autogenerated by Sphinx. Refer to documentation
6875
# for a list of supported languages.

‎docs/contribute.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
Contribute
2+
==========
3+
4+
.. warning::
5+
6+
This documentation is currently a work in progress and is still rough
7+
around the edges. Not finding what you are looking for? Please open an
8+
issue describing your troubles on `python-twitch's github page`_!
9+
10+
11+
You are welcome to contribute. Post your issues on `python-twitch's github
12+
page`_ with your feature suggestions and your problems.
13+
14+
Pull requests are required to be compatible with both Python 2.7 and recent
15+
versions of Python 3. To help you ensure good code quality CI is automatically
16+
testing all PR's and tells you if something is wrong with them.
17+
18+
.. note::
19+
20+
TODO: the document should also talk about style (flake8) and the necessity
21+
of adding tests to cover all code changes.
22+
23+
24+
.. Links
25+
26+
.. _twitch: http://www.twitch.tv/
27+
.. _Python: http://www.python.org/
28+
.. _`python-twitch's github page`: https://github.com/ingwinlu/python-twitch

‎docs/index.rst‎

Lines changed: 44 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,59 @@
1-
.. python-twitch documentation master file, created by
2-
sphinx-quickstart on Sat Oct 3 15:25:47 2015.
3-
You can adapt this file completely to your liking, but it should at least
4-
contain the root `toctree` directive.
1+
python-twitch |version|
2+
=======================
53

6-
Welcome to python-twitch's documentation!
7-
=========================================
4+
.. warning::
5+
6+
This documentation is currently a work in progress and is still rough
7+
around the edges. Not finding what you are looking for? Please open an
8+
issue describing your troubles on `python-twitch's github page`_!
9+
10+
11+
**python-twitch** is a library designed for easy access to the twitch_ api's. It
12+
is written in Python_ and enables you to access most of the functionality of the
13+
official twitch-api documentation while also offering an interface towards their
14+
hidden api and usher services.
15+
16+
17+
Features
18+
--------
19+
20+
python-twitch |version| currently supports:
21+
22+
* access to twitch api's
23+
+ v3 api
24+
+ hidden api
25+
+ usher api
26+
* translation of m3u8 playlists into more friendly json format
27+
* tests!
828

929
Contents:
30+
---------
1031

1132
.. toctree::
1233
:maxdepth: 2
1334

35+
quickstart
36+
contribute
37+
38+
API Reference
39+
-------------
40+
41+
.. toctree::
42+
:maxdepth: 2
1443

44+
api
1545

46+
1647
Indices and tables
17-
==================
48+
------------------
1849

1950
* :ref:`genindex`
2051
* :ref:`modindex`
2152
* :ref:`search`
2253

54+
55+
.. Links
56+
57+
.. _twitch: http://www.twitch.tv/
58+
.. _Python: http://www.python.org/
59+
.. _`python-twitch's github page`: https://github.com/ingwinlu/python-twitch

‎docs/quickstart.rst‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
Quickstart
2+
==========
3+
4+
.. warning::
5+
6+
This documentation is currently a work in progress and is still rough
7+
around the edges. Not finding what you are looking for? Please open an
8+
issue describing your troubles on `python-twitch's github page`_!
9+
10+
11+
Installation
12+
------------
13+
14+
python-twitch can be installed via::
15+
16+
pip install python-twitch
17+
18+
For a more unstable version you can directly install from the github
19+
repository::
20+
21+
pip install -e git+https://github.com/ingwinlu/python-twitch
22+
23+
24+
Dependencies
25+
------------
26+
27+
python-twitch supports Python 2.7 and Python 3.3+. It's only dependency is six_
28+
which should be automatically be installed when you install python-twitch.
29+
30+
31+
Usage
32+
-----
33+
34+
No additional setup is required, choose which API's you want to use and import
35+
them. python-twitch also does some logging. For troubleshooting add a handler to
36+
`twitch.logging.log`.
37+
38+
39+
API
40+
+++
41+
42+
Choose which ever API's you want to use and import them into your project::
43+
44+
from twitch.api import v3
45+
v3.streams.all(limit=1)
46+
47+
48+
Responses
49+
+++++++++
50+
51+
All queries executed over python-twitch result in json responses. You can find
52+
more information on them on the official twitch api documentation. Inofficial
53+
api's don't have any documentation and might get changed anytime, so don't build
54+
reliable systems around them and expect the results to change without warning.
55+
56+
57+
Logging
58+
+++++++
59+
60+
To have access to python-twitchs logging output add a handler to
61+
twitch.logging.log::
62+
63+
import logging
64+
from twitch.logging import log
65+
66+
console_handler = logging.StreamHandler()
67+
console_handler.setLevel(logging.INFO)
68+
formatter = logging.Formatter(
69+
'%(asctime)s - %(name)s - %(levelname)s - %(message)s')
70+
log.addHandler(console_handler)
71+
72+
73+
.. links:
74+
75+
.. _six: http://pythonhosted.org/six/
76+
.. _`python-twitch's github page`: https://github.com/ingwinlu/python-twitch

‎twitch/api/v3/__init__.py‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,26 @@
11
# -*- encoding: utf-8 -*-
2-
# https://github.com/justintv/Twitch-API/blob/master/v3_resources/
2+
"""
3+
twitch.api.v3
4+
-------------
5+
6+
Accumulate functionality from all submodules
7+
https://github.com/justintv/Twitch-API/blob/master/v3_resources/
8+
9+
.. autofunction:: twitch.api.v3.root()
10+
11+
.. automodule:: twitch.api.v3.blocks
12+
.. automodule:: twitch.api.v3.channels
13+
.. automodule:: twitch.api.v3.chat
14+
.. automodule:: twitch.api.v3.follows
15+
.. automodule:: twitch.api.v3.games
16+
.. automodule:: twitch.api.v3.ingests
17+
.. automodule:: twitch.api.v3.search
18+
.. automodule:: twitch.api.v3.streams
19+
.. automodule:: twitch.api.v3.subscriptions
20+
.. automodule:: twitch.api.v3.teams
21+
.. automodule:: twitch.api.v3.users
22+
.. automodule:: twitch.api.v3.videos
23+
"""
324

425
from twitch.api.v3 import blocks # NOQA
526
from twitch.api.v3 import channels # NOQA

‎twitch/api/v3/blocks.py‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# -*- encoding: utf-8 -*-
2-
# https://github.com/justintv/Twitch-API/blob/master/v3_resources/blocks.md
2+
"""
3+
twitch.api.v3.blocks
4+
~~~~~~~~~~~~~~~~~~~~
5+
6+
This module implements the functionality described here
7+
https://github.com/justintv/Twitch-API/blob/master/v3_resources/blocks.md
8+
"""
39

410
from twitch.queries import query
511

‎twitch/api/v3/channels.py‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# -*- encoding: utf-8 -*-
2-
# https://github.com/justintv/Twitch-API/blob/master/v3_resources/channels.md
2+
"""
3+
twitch.api.v3.channels
4+
~~~~~~~~~~~~~~~~~~~~~~
5+
6+
This module implements the functionality described here
7+
https://github.com/justintv/Twitch-API/blob/master/v3_resources/channels.md
8+
9+
.. autofunction:: by_name(name)
10+
.. autofunction:: teams(name)
11+
"""
312

413
from twitch import keys
514
from twitch.queries import V3Query as Qry
@@ -10,6 +19,11 @@
1019

1120
@query
1221
def by_name(name):
22+
"""Get channel object by name.
23+
24+
:param name: Name of the channel
25+
:returns: Channel Object as JSON
26+
"""
1327
q = Qry('channels/{channel}')
1428
q.add_urlkw(keys.CHANNEL, name)
1529
return q
@@ -21,9 +35,11 @@ def channel():
2135

2236

2337
def get_videos(name, **kwargs):
38+
"""Synonym for videos.by_channel"""
2439
return by_channel(name, **kwargs)
2540

2641

42+
# TODO needs authentification
2743
@query
2844
def editors(name):
2945
raise NotImplementedError
@@ -49,6 +65,11 @@ def commercial(name, length=30):
4965

5066
@query
5167
def teams(name):
68+
"""Returns team objects associated with the channel
69+
70+
:param name: Name of the channel
71+
:returns: Channel Object as JSON
72+
"""
5273
q = Qry('channels/{channel}/teams')
5374
q.add_urlkw('channel', name)
5475
return q

‎twitch/api/v3/chat.py‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
# -*- encoding: utf-8 -*-
2-
# https://github.com/justintv/Twitch-API/blob/master/v3_resources/chat.md
2+
"""
3+
twitch.api.v3.chat
4+
~~~~~~~~~~~~~~~~~~
5+
6+
This module implements the functionality described here
7+
https://github.com/justintv/Twitch-API/blob/master/v3_resources/chat.md
8+
9+
.. autofunction:: by_channel(name)
10+
.. autofunction:: badges(name)
11+
.. autofunction:: emoticons()
12+
"""
313

414
from twitch import keys
515
from twitch.queries import V3Query as Qry
@@ -8,19 +18,33 @@
818

919
@query
1020
def by_channel(name):
21+
"""Get links object to other chat endpoints
22+
23+
:param name: Name of the channel
24+
:returns: JSON Object describing other chat endpoints
25+
"""
1126
q = Qry('chat/{channel}')
1227
q.add_urlkw(keys.CHANNEL, name)
1328
return q
1429

1530

1631
@query
1732
def badges(name):
33+
"""Get chat badges for channel
34+
35+
:param name: Name of the channel
36+
:returns: JSON Object describing all channel badges
37+
"""
1838
q = Qry('chat/{channel}/badges')
1939
q.add_urlkw(keys.CHANNEL, name)
2040
return q
2141

2242

2343
@query
2444
def emoticons():
45+
"""Returns a list of all emoticon objects for Twitch.
46+
47+
:returns: JSON Object describing all emoticon objects
48+
"""
2549
q = Qry('chat/emoticons')
2650
return q

0 commit comments

Comments
 (0)