Updated docs

hidekuma · Apr 14, 2020 · c236eb8 · c236eb8
1 parent 39753b1
commit c236eb8
Show file tree

Hide file tree

Showing 36 changed files with 15,822 additions and 1 deletion.
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/Makefile b/docs/Makefile
@@ -6,7 +6,9 @@
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
-BUILDDIR      = build
+#BUILDDIR      = build
+BUILDDIR      = .
+
 
 # Put it first so that "make" without argument is like "make help".
 help:

diff --git a/docs/doctrees/environment.pickle b/docs/doctrees/environment.pickle
diff --git a/docs/doctrees/index.doctree b/docs/doctrees/index.doctree
diff --git a/docs/doctrees/usage/installation.doctree b/docs/doctrees/usage/installation.doctree
diff --git a/docs/doctrees/usage/quickstart.doctree b/docs/doctrees/usage/quickstart.doctree
diff --git a/docs/doctrees/usage/templates.doctree b/docs/doctrees/usage/templates.doctree
diff --git a/docs/html/.buildinfo b/docs/html/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 026473209c0a4603cd8e3cc69799f331
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/html/_sources/index.rst.txt b/docs/html/_sources/index.rst.txt
@@ -0,0 +1,46 @@
+.. Flask-S3Up documentation master file, created by
+   sphinx-quickstart on Mon Apr 13 17:07:44 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. meta::
+    :description: The Sphinx documentation builder
+    :keywords: Sphinx, documentation, builder
+
+
+Welcome to Flask-S3Up's documentation!
+======================================
+Flask S3up is a powerful extension that makes it easy to browse S3 in any Flask application. If you are familiar with Flask, Flask S3up should be easy to pick up.
+
+.. image:: https://raw.githubusercontent.com/hidekuma/flask-s3up/master/i/logo.png
+    :width: 200
+    :alt: Flask-S3Up-logo
+
+|PyPI version| |Build Status| |Maintenance| |made-with-python|
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+    Installation <usage/installation>
+    Quick start <usage/quickstart>
+    Controll Templates <usage/templates>
+    License <https://github.com/hidekuma/flask-s3up/blob/master/LICENSE>
+
+.. * :ref:`modindex`
+.. * :ref:`search`
+
+Show video on youtube:
+
+|flask-s3up-video|
+
+.. |PyPI version| image:: https://badge.fury.io/py/flask-s3up.svg
+   :target: https://badge.fury.io/py/flask-s3up
+.. |Build Status| image:: https://travis-ci.org/hidekuma/flask-s3up.svg?branch=master
+   :target: https://travis-ci.org/hidekuma/flask-s3up
+.. |Maintenance| image:: https://img.shields.io/badge/Maintained%3F-yes-green.svg
+   :target: https://github.com/hidekuma/flask-s3up/graphs/commit-activity
+.. |made-with-python| image:: https://img.shields.io/badge/Made%20with-Python-1f425f.svg
+   :target: https://www.python.org/
+.. |flask-s3up-video| image:: http://img.youtube.com/vi/yk6h6ym6Diw/0.jpg
+   :target: https://youtu.be/yk6h6ym6Diw?t=0s
diff --git a/docs/html/_sources/usage/installation.rst.txt b/docs/html/_sources/usage/installation.rst.txt
@@ -0,0 +1,24 @@
+Installation
+============
+You can `download FlaskS3Up executable`_ and `binary distributions from PyPI`_
+
+.. _download FlaskS3Up executable: https://github.com/hidekuma/flask-s3up/releases
+.. _binary distributions from PyPI: https://pypi.org/project/flask-s3up/
+
+Support versions
+----------------------------------------
+
+======= ====== ========
+Type    Name   Version
+======= ====== ========
+Runtime Python >=3.7
+Library boto3  >=1.12.2
+Library click  >=7.1.1
+Library Flask  >=1.1.1
+======= ====== ========
+
+Using pip
+---------
+.. code-block:: bash
+
+    pip install flask_s3up
diff --git a/docs/html/_sources/usage/quickstart.rst.txt b/docs/html/_sources/usage/quickstart.rst.txt
@@ -0,0 +1,229 @@
+Quick Start
+============
+
+Minimum setting
+---------------
+
+First install the dependency packages and configure.
+
+.. code-block:: bash
+
+    pip install flask flask_s3up
+
+Import flask and flask_s3up
+
+.. code-block:: python
+    :linenos:
+    :emphasize-lines: 3-4
+
+    import flask
+
+    from flask_s3up import FlaskS3Up
+    from flask_s3up.aws.ref import Region
+
+Initiailize Flask application and FlaskS3Up.
+
+.. code-block:: python
+    :linenos:
+    :emphasize-lines: 4-20
+
+    # Init Flask
+    app = Flask(__name__)
+
+    # Init Flask S3Up
+    s3up = FlaskS3Up(
+        # Flask App
+        app,
+        # Namespace must be unique
+        namespace='flask-s3up',
+        # Hostname, e.g. Cloudfront endpoint
+        object_hostname='http://flask-s3up.com',
+        # Put your AWS's profile name and Bucket name
+        config={
+            'profile_name': 'PROFILE_NAME',
+            'bucket_name': 'S3_BUCKET_NAME'
+        }
+    )
+
+    # Register Flask S3Up's router
+    s3up.register()
+
+    if __name__ == '__main__':
+        app.run(debug=True, port=3000)
+
+The values in the code above are mandatory. If the setting is finished, run your Flask application and visit ``http://localhost/{namespace}/files``, e.g. http://localhost:3000/flask-s3up/files.
+
+You can get example codes over here_.
+
+.. _here: https://github.com/hidekuma/flask-s3up/tree/master/example
+
+
+Multiple bucket settings
+------------------------
+You can also initiailize multiple bucket.
+
+.. code-block:: python
+    :linenos:
+    :emphasize-lines: 7-8
+
+    ...
+
+    s3up = FlaskS3Up(
+        ...
+    )
+
+    # Init another bucket
+    s3up.add_new_one(
+        namespace='another_namespace',
+        object_hostname='http://anotherbucket.com',
+        config={
+            'profile_name': 'PROFILE_NAME',
+            'bucket_name': 'S3_BUCKET_NAME'
+        }
+    )
+    s3up.register()
+
+Limit the file extensions
+--------------------------
+You can limit the file extensions that are uploaded, if you want.
+
+.. code-block:: python
+    :linenos:
+    :emphasize-lines: 4-5
+
+    s3up = FlaskS3Up(
+        ...
+
+        # allowed extension
+        allowed_extensions={'jpg', 'jpeg'},
+        config={
+            ...
+        }
+    )
+
+Choose the design template
+---------------------------
+Flask S3up supports the templates below.
+
+================== ==================== ============================
+Template namespace Design type          Description
+================== ==================== ============================
+base               *Default*             Not designed at all
+mdl                Material Design Lite `link <https://getmdl.io>`__
+================== ==================== ============================
+
+.. code-block:: python
+    :linenos:
+    :emphasize-lines: 3-4
+
+    s3up = FlaskS3Up(
+        ...
+        # Enter template namespace (default: base)
+        template_namespace='mdl',
+        config={
+            ...
+        }
+    )
+    s3up.register()
+
+Controll large files
+--------------------
+If you want to controll large files (maybe larger than 5MB ~ maximum 5TB), I recommand to set like below.
+Flask S3Up is going to use S3's presigned URL. It's nice to controll large files.
+
+.. code-block:: python
+    :linenos:
+    :emphasize-lines: 3-4
+
+    s3up = FlaskS3Up(
+        ...
+        # Change upload type to 'presign'
+        upload_type='presign',
+        config={
+            ...
+        }
+    )
+    s3up.register()
+
+but you must do S3’s CORS settings before like set above.
+
+.. code-block:: xml
+    :linenos:
+
+     <CORSConfiguration>
+         <CORSRule>
+             <AllowedOrigin>http://www.yourdomain.com</AllowedOrigin>
+             <AllowedMethod>GET</AllowedMethod>
+             <AllowedMethod>POST</AllowedMethod>
+             <AllowedHeader>*</AllowedHeader>
+         </CORSRule>
+     </CORSConfiguration>
+
+Use Caching
+-----------
+S3 is charged per call. Therefore, Flask S3Up supports caching (currently only supports file caching, in-memory database will be supported later).
+
+.. code-block:: python
+    :linenos:
+    :emphasize-lines: 5-10
+
+    s3up = FlaskS3Up(
+        ...
+        config={
+            ...
+            # Flask S3Up will cache the list of s3 objects, if you set True
+            'use_cache': True,
+            # Where cached files will be written
+            'cache_dir': '/tmp/flask_s3up',
+            # Time To Live
+            'ttl': 86400
+        }
+    )
+    s3up.register()
+
+Full example
+------------
+
+.. code-block:: python
+    :linenos:
+
+    ...
+
+     s3up = FlaskS3Up(
+         # Flask app
+         app,
+         # Namespace must be unique
+         namespace='flask-s3up',
+         # Enter template namespace(default: base)
+         template_namespace='mdl',
+         # File's hostname
+         object_hostname='http://flask-s3up.com',
+         # Allowed extension
+         allowed_extensions={},
+         # Bucket configs and else
+         config={
+             # Required
+             'profile_name': 'PROFILE_NAME',
+             # Required
+             'bucket_name': 'S3_BUCKET_NAME',
+             'region_name': Region.SEOUL.value,
+             # Not necessary, if you configure aws settings, e.g. ~/.aws
+             'access_key': 'AWS_IAM_ACCESS_KEY',
+             'secret_key': 'AWS_IAM_SECRET_KEY',
+             # For S3 compatible
+             'endpoint_url': None,
+             # Flask S3Up will cache the list of s3 objects, if you set True
+             'use_cache': True,
+             # Where cached files will be written
+             'cache_dir': '/tmp/flask_s3up',
+             # Time To Live
+             'ttl': 86400,
+         }
+     )
+
+Things to know
+--------------
+
+Searching
+`````````
+- Search only working in EN, because of JMESPath.
diff --git a/docs/html/_sources/usage/templates.rst.txt b/docs/html/_sources/usage/templates.rst.txt
@@ -0,0 +1,65 @@
+Controll Templates
+==================
+
+Use CLI tool
+------------
+You can customize template with CLI tool.
+
+See help.
+
+.. code-block:: bash
+
+    # You can see the details
+    flask_s3up -h
+
+     ____  __     __   ____  __ _    ____  ____  _  _  ____
+    (  __)(  )   / _\ / ___)(  / )  / ___)( __ \/ )( \(  _ \
+     ) _) / (_/\/    \\___ \ )  (   \___ \ (__ () \/ ( ) __/
+    (__)  \____/\_/\_/(____/(__\_)  (____/(____/\____/(__)
+
+    ============= Flask S3Up Command Line Tool ==============
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      -p PATH, --path PATH  Enter the directory path where the template will be
+                            located
+      -t {base,mdl}, --template {base,mdl}
+                            Enter the name of the template to import. (mdl means
+                            material-design-lite and base means not designed
+                            template).
+
+Get the template to your repository.
+
+.. code-block:: bash
+
+    # Get a Material-design-lite template
+    flask_s3up --path templates/mdl --template mdl
+
+    # Get a base template (not designed at all)
+    flask_s3up -p templates/base -t base
+
+
+When you run the command, you can see the
+``{repository}/{path}/{template}`` has been created on your
+repository. then rerun the Flask application.
+
+And you can also change template directory if you want.
+
+For examples, Get Material-design-lite template to ``templates/customized`` directory on your root path.
+
+.. code-block:: bash
+
+   flask_s3up -p templates/customized -t mdl
+
+Then change template_namespace. it will be routed to defined directory (``templates/customized``).
+
+.. code-block:: bash
+
+   s3up = FlaskS3Up(
+       ...
+       template_namespace='customized',
+       ...
+   )
+
+.. warning::
+    The template folder of Flask S3Up is fixed as ``templates``. so if you change ``template_namespace``, It will be routed ``{repository}/templates/{defined template_namespace_by_you}``.