Skip to content

Commit 09a68ba

Browse files
authoredApr 22, 2019
Migrate the README to markdown (#463)
* Migrate the README to markdown * Upgrade Sphinx to support markdown README
·
9.7.06.26.2
1 parent 2139fad commit 09a68ba

File tree

9 files changed

+161
-261
lines changed

9 files changed

+161
-261
lines changed
 

‎Dockerfile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ WORKDIR /twilio
77

88
COPY setup.py .
99
COPY requirements.txt .
10-
COPY README.rst .
10+
COPY README.md .
1111
COPY twilio ./twilio
1212

1313
RUN pip install .

‎README.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# twilio-python
2+
3+
[![Build Status](https://secure.travis-ci.org/twilio/twilio-python.png?branch=master)](http://travis-ci.org/twilio/twilio-python)
4+
[![PyPI](https://img.shields.io/pypi/v/twilio.svg)](https://pypi.python.org/pypi/twilio)
5+
[![PyPI](https://img.shields.io/pypi/pyversions/twilio.svg)](https://pypi.python.org/pypi/twilio)
6+
7+
A module for using the Twilio REST API and generating valid
8+
[TwiML](http://www.twilio.com/docs/api/twiml/ "TwiML -
9+
Twilio Markup Language").
10+
11+
## Recent Update
12+
13+
As of release 6.5.0, Beta and Developer Preview products are now exposed via
14+
the main `twilio-python` artifact. Releases of the `alpha` branch have been
15+
discontinued.
16+
17+
If you were using the `alpha` release line, you should be able to switch back
18+
to the normal release line without issue.
19+
20+
If you were using the normal release line, you should now see several new
21+
product lines that were historically hidden from you due to their Beta or
22+
Developer Preview status. Such products are explicitly documented as
23+
Beta/Developer Preview both in the Twilio docs and console, as well as through
24+
in-line code documentation here in the library.
25+
26+
## Installation
27+
28+
Install from PyPi using [pip](http://www.pip-installer.org/en/latest/), a
29+
package manager for Python.
30+
31+
pip install twilio
32+
33+
Don't have pip installed? Try installing it, by running this from the command
34+
line:
35+
36+
$ curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python
37+
38+
Or, you can [download the source code
39+
(ZIP)](https://github.com/twilio/twilio-python/zipball/master "twilio-python
40+
source code") for `twilio-python`, and then run:
41+
42+
python setup.py install
43+
44+
You may need to run the above commands with `sudo`.
45+
46+
### Migrate from 5.x
47+
Please consult the [official migration guide](https://www.twilio.com/docs/libraries/python/migration-guide) for information on upgrading your application using twilio-python 5.x to 6.x
48+
49+
## Getting Started
50+
51+
Getting started with the Twilio API couldn't be easier. Create a
52+
`Client` and you're ready to go.
53+
54+
### API Credentials
55+
56+
The `Twilio` needs your Twilio credentials. You can either pass these
57+
directly to the constructor (see the code below) or via environment variables.
58+
59+
```python
60+
from twilio.rest import Client
61+
62+
account = "ACXXXXXXXXXXXXXXXXX"
63+
token = "YYYYYYYYYYYYYYYYYY"
64+
client = Client(account, token)
65+
```
66+
67+
Alternately, a `Client` constructor without these parameters will
68+
look for `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` variables inside the
69+
current environment.
70+
71+
We suggest storing your credentials as environment variables. Why? You'll never
72+
have to worry about committing your credentials and accidentally posting them
73+
somewhere public.
74+
75+
76+
```python
77+
from twilio.rest import Client
78+
client = Client()
79+
```
80+
81+
### Make a Call
82+
83+
```python
84+
from twilio.rest import Client
85+
86+
account = "ACXXXXXXXXXXXXXXXXX"
87+
token = "YYYYYYYYYYYYYYYYYY"
88+
client = Client(account, token)
89+
90+
call = client.calls.create(to="9991231234",
91+
from_="9991231234",
92+
url="http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
93+
print(call.sid)
94+
```
95+
96+
### Send an SMS
97+
98+
```python
99+
from twilio.rest import Client
100+
101+
account = "ACXXXXXXXXXXXXXXXXX"
102+
token = "YYYYYYYYYYYYYYYYYY"
103+
client = Client(account, token)
104+
105+
message = client.messages.create(to="+12316851234", from_="+15555555555",
106+
body="Hello there!")
107+
```
108+
109+
### Handling a call using TwiML
110+
111+
To control phone calls, your application needs to output
112+
[TwiML](http://www.twilio.com/docs/api/twiml/ "TwiML - Twilio Markup
113+
Language"). Use `twilio.twiml.Response` to easily create such responses.
114+
115+
```python
116+
from twilio.twiml.voice_response import VoiceResponse
117+
118+
r = VoiceResponse()
119+
r.say("Welcome to twilio!")
120+
print(str(r))
121+
```
122+
123+
```xml
124+
<?xml version="1.0" encoding="utf-8"?>
125+
<Response><Say>Welcome to twilio!</Say></Response>
126+
```
127+
128+
### Docker Image
129+
130+
The `Dockerfile` present in this repository and its respective `twilio/twilio-python` Docker image are currently used by Twilio for testing purposes only.
131+
132+
### Getting help
133+
134+
If you need help installing or using the library, please check the [Twilio Support Help Center](https://support.twilio.com) first, and [file a support ticket](https://twilio.com/help/contact) if you don't find an answer to your question.
135+
136+
If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!

‎README.rst

Lines changed: 0 additions & 161 deletions
This file was deleted.

‎deploy.py

Lines changed: 0 additions & 78 deletions
This file was deleted.

‎docs/conf.py

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
# -- Project information -----------------------------------------------------
2424

2525
project = 'twilio-python'
26-
copyright = '2018, Twilio'
26+
copyright = '2019, Twilio'
2727
author = 'Twilio'
2828

2929
# The short X.Y version
@@ -48,6 +48,7 @@
4848
'sphinx.ext.coverage',
4949
'sphinx.ext.ifconfig',
5050
'sphinx.ext.viewcode',
51+
'recommonmark'
5152
]
5253

5354
# Add any paths that contain templates here, relative to this directory.
@@ -56,8 +57,10 @@
5657
# The suffix(es) of source filenames.
5758
# You can specify multiple suffix as a list of string:
5859
#
59-
# source_suffix = ['.rst', '.md']
60-
source_suffix = '.rst'
60+
source_suffix = {
61+
'.rst': 'restructuredtext',
62+
'.md': 'markdown',
63+
}
6164

6265
# The master toctree document.
6366
master_doc = 'index'
@@ -190,4 +193,4 @@
190193
# -- Options for intersphinx extension ---------------------------------------
191194

192195
# Example configuration for intersphinx: refer to the Python standard library.
193-
intersphinx_mapping = {'https://docs.python.org/': None}
196+
intersphinx_mapping = {'https://docs.python.org/': None}

‎index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Release v\ |version|.
1212
.. toctree::
1313
:maxdepth: 2
1414

15-
readme_include
15+
README.md
1616

1717

1818
API auto-generated documentation

‎readme_include.rst

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎setup.py

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
11
from __future__ import with_statement
2-
import sys
32
from setuptools import setup, find_packages
43

54
__version__ = None
65
with open('twilio/__init__.py') as f:
76
exec(f.read())
87

9-
with open('README.rst') as f:
8+
with open('README.md') as f:
109
long_description = f.read()
1110

1211
# To install the twilio-python library, open a Terminal shell, then run this
@@ -18,14 +17,14 @@
1817
# documentation: http://pypi.python.org/pypi/setuptools
1918

2019
setup(
21-
name = "twilio",
22-
version = __version__,
23-
description = "Twilio API client and TwiML generator",
24-
author = "Twilio",
25-
author_email = "help@twilio.com",
26-
url = "https://github.com/twilio/twilio-python/",
27-
keywords = ["twilio","twiml"],
28-
install_requires = [
20+
name="twilio",
21+
version=__version__,
22+
description="Twilio API client and TwiML generator",
23+
author="Twilio",
24+
author_email="help@twilio.com",
25+
url="https://github.com/twilio/twilio-python/",
26+
keywords=["twilio", "twiml"],
27+
install_requires=[
2928
"six",
3029
"pytz",
3130
"PyJWT >= 1.4.2",
@@ -39,9 +38,9 @@
3938
"pysocks",
4039
],
4140
},
42-
packages = find_packages(exclude=['tests', 'tests.*']),
41+
packages=find_packages(exclude=['tests', 'tests.*']),
4342
include_package_data=True,
44-
classifiers = [
43+
classifiers=[
4544
"Development Status :: 5 - Production/Stable",
4645
"Intended Audience :: Developers",
4746
"License :: OSI Approved :: MIT License",
@@ -53,6 +52,7 @@
5352
"Programming Language :: Python :: 3.6",
5453
"Topic :: Software Development :: Libraries :: Python Modules",
5554
"Topic :: Communications :: Telephony",
56-
],
57-
long_description = long_description
55+
],
56+
long_description=long_description,
57+
long_description_content_type='text/markdown'
5858
)

‎tests/requirements.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Sphinx==1.7.6
1+
Sphinx==1.8.0
22
mock==0.8.0
33
nose
44
coverage
@@ -8,3 +8,4 @@ mccabe
88
wheel>=0.22.0
99
cryptography
1010
twine
11+
recommonmark

0 commit comments

Comments
 (0)
Please sign in to comment.