From 896808dfe1cdedc1ff0281903e8b58cb3061b6b9 Mon Sep 17 00:00:00 2001 From: Kumar Appaiah Date: Tue, 8 Dec 2009 11:31:18 -0600 Subject: [PATCH] Add initial Sphinx documentation. Signed-off-by: Joshua Roesslein --- doc/.gitignore | 1 + doc/Makefile | 99 ++++++++++++++++++++ doc/api.rst | 12 +++ doc/auth_tutorial.rst | 163 +++++++++++++++++++++++++++++++++ doc/code_snippet.rst | 61 +++++++++++++ doc/conf.py | 195 ++++++++++++++++++++++++++++++++++++++++ doc/getting_started.rst | 66 ++++++++++++++ doc/index.rst | 25 ++++++ doc/make.bat | 113 +++++++++++++++++++++++ 9 files changed, 735 insertions(+) create mode 100644 doc/.gitignore create mode 100644 doc/Makefile create mode 100644 doc/api.rst create mode 100644 doc/auth_tutorial.rst create mode 100644 doc/code_snippet.rst create mode 100644 doc/conf.py create mode 100644 doc/getting_started.rst create mode 100644 doc/index.rst create mode 100644 doc/make.bat diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..e35d885 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +_build diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..5d97e1a --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,99 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + mkdir -p $(BUILDDIR)/html + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + mkdir -p $(BUILDDIR)/dirhtml + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +pickle: + mkdir -p $(BUILDDIR)/pickle + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + mkdir -p $(BUILDDIR)/json + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + mkdir -p $(BUILDDIR)/htmlhelp + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + mkdir -p $(BUILDDIR)/qthelp + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/tweepy.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/tweepy.qhc" + +latex: + mkdir -p $(BUILDDIR)/latex + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + mkdir -p $(BUILDDIR)/changes + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + mkdir -p $(BUILDDIR)/linkcheck + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + mkdir -p $(BUILDDIR)/doctest + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/api.rst b/doc/api.rst new file mode 100644 index 0000000..ff3ba3b --- /dev/null +++ b/doc/api.rst @@ -0,0 +1,12 @@ +.. _api_reference: + +API Reference +============= + +This page contains some basic documentation for the Tweepy module. + +:mod:`tweepy` Module +--------------------- + +TODO + diff --git a/doc/auth_tutorial.rst b/doc/auth_tutorial.rst new file mode 100644 index 0000000..7f87220 --- /dev/null +++ b/doc/auth_tutorial.rst @@ -0,0 +1,163 @@ +.. _auth_tutorial: + + +*********************** +Authentication Tutorial +*********************** + +Introduction +============ + +Tweepy supports both basic and oauth authentication. Authentication is +handled by tweepy.AuthHandler classes with two implementations +provided: + +* OAuthHandler + +* BasicAuthHandler + +Basic Authentication +==================== + +Basic authentication uses the user's Twitter username and password for +authenticating with the API. You must query the user for these two +pieces of infomation before we can authenticate. + +Now first we must create an instance of the BasicAuthHandler and pass +into it the username and password:: + + auth = tweepy.BasicAuthHandler(username, password) + +Next we need to create our API instance which will be used for +executing requests to the Twitter API:: + + api = tweepy.API(auth) + +We are now ready to make API calls that are authenticated! Here is a +quick example posting a new tweet to the authenticated user's account:: + + api.update_status('hello from tweepy!') + +OAuth Authentication +==================== + +OAuth is a bit trickier than basic auth, but there are some advantages +to using it: + +* You can set a 'from myappname' which will appear in tweets + posted + +* More secure since you don't need the user's password + +* Your app does not break if the user changes their password in + the future + +Tweepy tries to make OAuth as painless as possible for you. To begin +the process we need to register our client application with +Twitter. You can do that here. Create a new application and once you +are done you should have your consumer token and secret. Keep these +two handy, you'll need them. + +The next step is creating an OAuthHandler instance. Into this we pass +our consumer token and secret which was given to us in the previous +paragraph:: + + auth = tweepy.OAuthHandler(consumer_token, consumer_secret) + +If you have a web application and are using a callback URL that needs +to be supplied dynamically you would pass it in like so:: + + auth = tweepy.OAuthHandler(consumer_token, consumer_secret, + callback_url) + +If the callback URL will not be changing, it is best to just configure +it statically on twitter.com when setting up your application's +profile. + +Unlike basic auth, we must do the OAuth "dance" before we can start +using the API. We must complete the following steps: + +#. Get a request token from twitter + +#. Redirect user to twitter.com to authorize our application + +#. If using a callback, twitter will redirect the user to + us. Otherwise the user must manually supply us with the verifier + code. + +#. Exchange the authorized request token for an access token. + +So let's fetch our request token to begin the dance:: + + try: + redirect_url = auth.get_authorization_url() + except tweepy.TweepError: + print 'Error! Failed to get request token.' + +This call requests the token from twitter and returns to us the +authorization URL where the user must be redirect to authorize us. Now +if this is a desktop application we can just hang onto our +OAuthHandler instance until the user returns back. In a web +application we will be using a callback request. So we must store the +request token in the session since we will need it inside the callback +URL request. Here is a pseudo example of storing the request token in +a session:: + + session.set('request_token', (auth.request_token.key, + auth.request_token.secret) + +So now we can redirect the user to the URL returned to us earlier from +the get_authorization_url() method. + +If this is a desktop application (or any application not using +callbacks) we must query the user for the "verifier code" that twitter +will supply them after they authorize us. Inside a web application +this verifier value will be supplied in the callback request from +twitter as a GET query parameter in the URL. + +.. code-block :: python + + # Example using callback (web app) + verifier = request.GET.get('oauth_verifier') + + # Example w/o callback (desktop) + verifier = raw_input('Verifier:') + +The final step is exchanging the request token for an access +token. The access token is the "key" for opening the Twitter API +treasure box. To fetch this token we do the following:: + + # Let's say this is a web app, so we need to re-build the auth handler + # first... + auth = tweepy.OAuthHandler(consumer_key, consumer_secret) + token = session.get('request_token') + session.delete('request_token') + auth.set_request_token(token[0], token[1]) + + try: + auth.get_access_token(verifier) + except tweepy.TweepError: + print 'Error! Failed to get access token.' + +It is a good idea to save the access token for later use. You do not +need to re-fetch it each time. Twitter currently does not expire the +tokens, so the only time it would ever go invalid is if the user +revokes our application access. To store the access token depends on +your application. Basically you need to store 2 string values: key and +secret:: + + auth.access_token.key + auth.access_token.secret + +You can throw these into a database, file, or where ever you store +your data. To re-build an OAuthHandler from this stored access token +you would do this:: + + auth = tweepy.OAuthHandler(consumer_key, consumer_secret) + auth.set_access_token(key, secret) + +So now that we have our OAuthHandler equiped with an access token, we +are ready for business:: + + api = tweepy.API(auth) + api.update_status('tweepy + oauth!') diff --git a/doc/code_snippet.rst b/doc/code_snippet.rst new file mode 100644 index 0000000..13ea0ac --- /dev/null +++ b/doc/code_snippet.rst @@ -0,0 +1,61 @@ +.. _code_snippet: + + +************* +Code Snippets +************* + +Introduction +============ + +Here are some code snippets to help you out with using Tweepy. Feel +free to contribute your own snippets or improve the ones here! + +BasicAuth +========= + +.. code-block :: python + + auth = tweepy.BasicAuthHandler("username", "password") + api = tweepy.API(auth) + +OAuth +===== + +.. code-block :: python + + auth = tweepy.OAuthHandler("consumer_key", "consumer_secret") + + # Redirect user to Twitter to authorize + redirect_user(auth.get_authorization_url()) + + # Get access token + auth.get_access_token("verifier_value") + + # Construct the API instance + api = tweepy.API(auth) + +Pagination +========== + +.. code-block :: python + + # Iterate through all of the authenticated user's friends + for friend in tweepy.Cursor(api.friends).items(): + # Process the friend here + process_friend(friend) + + # Iterate through the first 200 statuses in the friends timeline + for status in tweepy.Cursor(api.friends_timeline).items(200): + # Process the status here + process_status(status) + +FollowAll +========= + +This snippet will follow every follower of the authenticated user. + +.. code-block :: python + + for follower in tweepy.Cursor(api.followers).items(): + follower.follow() diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..97c161d --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,195 @@ +# -*- coding: utf-8 -*- +# +# tweepy documentation build configuration file, created by +# sphinx-quickstart on Sun Dec 6 11:13:52 2009. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.append(os.path.abspath('.')) +sys.path.append(os.path.abspath('..')) + +# -- General configuration ----------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc'] + +# Add any paths that contain templates here, relative to this directory. +#templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'tweepy' +copyright = u'2009, Tweepy Authors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.4' +# The full version, including alpha/beta/rc tags. +release = '1.4' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +html_use_modindex = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'tweepydoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'tweepy.tex', u'tweepy Documentation', + u'Tweepy Authors', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True diff --git a/doc/getting_started.rst b/doc/getting_started.rst new file mode 100644 index 0000000..4f7a020 --- /dev/null +++ b/doc/getting_started.rst @@ -0,0 +1,66 @@ +.. _getting_started: + + +*************** +Getting started +*************** + +Introduction +============ + +If you are new to Tweepy, this is the place to begin. The goal of this +tutorial is to get you set-up and rolling with Tweepy. We won't go +into too much details here, just some important basics. + +Hello Tweepy +============ + +.. code-block :: python + + import tweepy + + public_tweets = tweepy.api.public_timeline() + for tweet in public_tweets: + print tweet.text + +This example will download the public timeline tweets and print each +one of their texts to the console. tweepy.api in the above code +snippet is an unauthenticated instance of the tweepy API class. The +API class contains all the methods for access the Twitter API. By +unauthenticated means there is no user associated with this +instance. So you may only do unauthenticated API calls with this +instance. For example the following would fail:: + + tweepy.api.update_status('will not work!') + +The :ref:`auth_tutorial` goes into more details about authentication. + +API +=== + +The API class provides access to the entire twitter RESTful API +methods. Each method can accept various parameters and return +responses. For more infomation about these methods please refer to +:ref:`api_reference`. + +Models +====== + +When we invoke an API method most of the time returned back to us will +be a Tweepy model class instance. This will contain the data returned +from Twitter which we can then use inside our application. For example +the following code returns to us an User model:: + + # Get the User object for twitter... + user = tweepy.api.get_user('twitter') + +Models container the data and some helper methods which we can then +use:: + + print user.screen_name + print user.followers_count + for friend in user.friends(): + print friend.screen_name + +For more information about models please see ModelsReference. + diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..230de25 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,25 @@ +.. tweepy documentation master file, created by + sphinx-quickstart on Sun Dec 6 11:13:52 2009. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to tweepy's documentation! +================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + getting_started.rst + auth_tutorial.rst + code_snippet.rst + api.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..10adbcd --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,113 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +set SPHINXBUILD=sphinx-build +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\tweepy.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\tweepy.ghc + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end -- 2.25.1