diff --git a/docs/conf.py b/docs/conf.py index af26c67..60bdfa7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,7 +16,7 @@ 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.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.abspath('../')) # -- General configuration ----------------------------------------------------- @@ -25,7 +25,7 @@ import sys, os # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -40,7 +40,7 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'flask-s3' +project = u'flask-S3' copyright = u'2012, Edward Robinson' # The version info for the project you're documenting, acts as replacement for @@ -67,6 +67,8 @@ release = '0.1' exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all documents. +default_role = 'obj' +# affects stuff wrapped like `this` #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. @@ -81,7 +83,7 @@ exclude_patterns = ['_build'] #show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +#pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] @@ -228,7 +230,7 @@ man_pages = [ # dir menu entry, description, category) texinfo_documents = [ ('index', 'flask-s3', u'flask-s3 Documentation', - u'Edward Robinson', 'flask-s3', 'One line description of project.', + u'Edward Robinson', 'flask-s3', 'Flask-S3 allows you to server your static assets from Amazon S3.', 'Miscellaneous'), ] @@ -244,3 +246,12 @@ texinfo_documents = [ sys.path.append(os.path.abspath('_themes')) html_theme_path = ['_themes'] html_theme = 'flask_small' +html_theme_options = dict(github_fork='e-dard/flask-s3', + index_logo=False) + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None, + 'http://flask.pocoo.org/docs/': None} + + diff --git a/docs/index.rst b/docs/index.rst index 270550c..a95940a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,22 +1,177 @@ -.. flask-s3 documentation master file, created by - sphinx-quickstart on Sat Sep 8 13:10:46 2012. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +Flask-S3 +******** +.. module:: flask_s3 -Welcome to flask-s3's documentation! -==================================== +Flask-S3 allows you to easily serve all your `Flask`_ application's static assets from `Amazon S3`_, without having to modify your templates. -Contents: +.. _Amazon S3: http://aws.amazon.com/s3 +.. _Flask: http://flask.pocoo.org/ -.. toctree:: - :maxdepth: 2 +How it works +============ + +Flask-S3 has two main functions: + + 1. Walk through your application's static folders, gather all your static assets together, and upload them to a bucket of your choice on S3; + + 2. Replace the URLs that Flask's :func:`flask.url_for` function would insert into your templates, with URLs that point to the static assets in your S3 bucket. + +The process of gathering and uploading your static assets to S3 need only be done once, and your application does not need to be running for it to work. The location of the S3 bucket can be inferred from Flask-S3 `settings`_ specified in your Flask application, therefore when your application is running there need not be any communication between the Flask application and Amazon S3. + +Internally, every time ``url_for`` is called in one of your application's templates, `flask_s3.url_for` is instead invoked. If the endpoint provided is deemed to refer to static assets, then the S3 URL for the asset specified in the `filename` argument is instead returned. Otherwise, `flask_s3.url_for` passes the call on to `flask.url_for`. + + +Installation +============ + +If you use pip then installation is simply:: + + $ pip install flask-s3 + +or, if you want the latest github version:: + + $ pip install git+git://github.com/e-dard/flask-s3.git + +You can also install Flask-S3 via Easy Install:: + + $ easy_install flask-s3 + +Dependencies +------------ + +Aside from the obvious dependency of Flask itself, Flask-S3 makes use of the +`boto`_ library for uploading assets to Amazon S3. **Note**: Flask-S3 currently +only supports applications that use the `jinja2`_ templating system. + +.. _boto: http://docs.pythonboto.org/en/latest/ +.. _jinja2: http://jinja.pocoo.org/docs/ + +Using Flask-S3 +============== + +Flask-S3 is incredibly simple to use. In order to start serving your Flask +application's assets from Amazon S3, the first thing to do is let Flask-S3 know +about your :class:`flask.Flask` application object. + +.. code-block:: python + + from flask import Flask + from flask_s3 import FlaskS3 + + app = Flask(__name__) + app.config['S3_BUCKET_NAME'] = 'mybucketname' + s3 = FlaskS3(app) + +In many cases, however, one cannot expect a Flask instance to be ready at +import time, and a common pattern is to return a Flask instance from within a +function only after other configuration details have been taken care of. In these +cases, Flask-S3 provides a simple function, ``init_app``, which takes your +application as an argument. + +.. code-block:: python + + from flask import Flask + from flask_s3 import FlaskS3 + + s3 = FlaskS3() + + def start_app(): + app = Flask(__name__) + s3.init_app(app) + return app + +In terms of getting your application to use external Amazon S3 URLs when +referring to your application's static assets, passing your ``Flask`` object to the ``FlaskS3`` object is all that needs to be done. Once your app is running, any templates that contained relative static asset locations, will instead contain hosted counterparts on Amazon S3. + +Uploading your Static Assets +---------------------------- + +You only need to upload your static assets to Amazon S3 once. Of course, if you add or modify your existing assets then you will need to repeat the uploading process. + +Uploading your static assets from a Python console is as simple as follows. + +.. code-block:: python + + >>> import flask_s3 + >>> from my_application import app + >>> flask_s3.create_all(app) + >>> + +Flask-S3 will proceed to walk through your application's static assets, +including those belonging to *registered* `blueprints`_, and upload them to your +Amazon S3 bucket. + +.. _blueprints: http://flask.pocoo.org/docs/blueprints/ + +Static Asset URLs +~~~~~~~~~~~~~~~~~ + +Within your bucket on S3, Flask-S3 replicates the static file hierarchy defined in your application object and any registered blueprints. URLs generated by Flask-S3 will look like the following: + +``/static/foo/style.css`` becomes +``https://mybucketname.s3.amazonaws.com/static/foo/style.css``, +assuming that ``mybucketname`` is the name of your S3 bucket, and you have +chosen to have assets served over HTTPS. + + +.. _settings: +.. _configuration: + +Flask-S3 Options +---------------- + +Within your Flask application's settings you can provide the following settings +to control the behvaiour of Flask-S3. None of the settings are required, but if +not present, some will need to be provided when uploading assets to S3. + +=========================== =================================================== +`AWS_ACCESS_KEY_ID` Your AWS access key. This does not need to be + stored in your configuration if you choose to pass + it directly when uploading your assets. +`AWS_SECRET_ACCESS_KEY` Your AWS secret key. As with the access key, this + need not be stored in your configuration if passed + in to `create_all`. +`S3_BUCKET_DOMAIN` The domain part of the URI for your S3 bucket. You + probably won't need to change this. + **Default:** ``u's3.amazonaws.com'`` +`S3_BUCKET_NAME` The desired name for your Amazon S3 bucket. Note: + the name will be visible in all your assets' URLs. +`S3_USE_HTTPS` Specifies whether or not to serve your assets + stored in S3 over HTTPS. + **Default:** `True` +`USE_S3` This setting allows you to toggle whether Flask-S3 + is active or not. When set to `False` your + application's templates will revert to including static asset locations determined by `flask.url_for`. + **Default:** `True` +`USE_S3_DEBUG` By default, Flask-S3 will be switched off when + running your application in `debug`_ mode, so that + your templates include static asset locations specified by `flask.url_for`. If you wish to enable Flask-S3 in debug mode, set this value to `True`. **Note**: if `USE_S3` is set to `False` then templates will always include asset locations specified by `flask.url_for`. +=========================== =================================================== + +.. _debug: http://flask.pocoo.org/docs/config/#configuration-basics + + + + +API Documentation +================= + +Flask-S3 is a very simple extension. The few exposed objects, methods and functions are as follows. + +The FlaskS3 Object +------------------ +.. autoclass:: FlaskS3 + + .. automethod:: init_app + + +S3 Interaction +-------------- +.. autofunction:: create_all + +.. autofunction:: url_for -Indices and tables -================== -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search`