wip on docs

DHI · Nov 23, 2018 · b1f68ce · b1f68ce
1 parent 08e10f9
commit b1f68ce
Show file tree

Hide file tree

Showing 15 changed files with 143 additions and 40 deletions.
diff --git a/README.rst b/README.rst
@@ -9,8 +9,7 @@ Terracotta? <#why-terracotta>`__ \| `Why not
 Terracotta? <#why-not-terracotta>`__ \| `Architecture <#architecture>`__
 \| `Installation <#installation>`__ \| `Ingestion <#ingestion>`__ \|
 `Web API <#web-api>`__ \| `Configuration <#configuration>`__ \|
-`Advanced recipes <#advanced-recipes>`__ \| `Known
-issues <#known-issues>`__
+`Advanced recipes <#advanced-recipes>`__
 
 A light-weight, versatile XYZ tile server, built with Flask and Rasterio
 :earth_africa:
@@ -452,28 +451,6 @@ Note that Zappa works best on Linux. Windows 10 users can use the
 Linux <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__ to
 deploy Terracotta.
 
-Known Issues
-------------
-
-The sections below outline some common issues people encounter when
-using Terracotta. If your problem persists, `feel free to open an
-issue <https://github.com/DHI-GRAS/terracotta/issues>`__.
-
-``OSError: error while reading file`` while deploying to AWS λ
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Rasterio Linux wheels are built on CentOS, which stores SSL certificates
-in ``/etc/pki/tls/certs/ca-bundle.crt``. On other Linux flavors,
-certificates may be stored in a different location. On Ubuntu, you can
-e.g. run
-
-.. code:: bash
-
-   $ export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
-
-to fix this issue. For more information, see
-`mapbox/rasterio#942 <https://github.com/mapbox/rasterio/issues/942>`__.
-
 .. |Build Status| image:: https://travis-ci.com/DHI-GRAS/terracotta.svg?token=27HwdYKjJ1yP6smyEa25&branch=master
    :target: https://travis-ci.org/DHI-GRAS/terracotta
 .. |Documentation Status| image:: https://readthedocs.org/projects/terracotta-python/badge/?version=latest

diff --git a/docs/api.rst b/docs/api.rst
@@ -22,8 +22,20 @@ Common interface
 Available drivers
 +++++++++++++++++
 
+SQLite
+~~~~~~
+
 .. autoclass:: terracotta.drivers.sqlite.SQLiteDriver
    :members: __init__
 
+Remote SQLite on S3
+~~~~~~~~~~~~~~~~~~~
+
 .. autoclass:: terracotta.drivers.sqlite_remote.RemoteSQLiteDriver
+   :members: __init__
+
+MySQL
+~~~~~
+
+.. autoclass:: terracotta.drivers.mysql.MySQLDriver
    :members: __init__
diff --git a/docs/cli.rst b/docs/cli.rst
@@ -1,14 +1,29 @@
 Command-line interface
 ======================
 
+.. program-output:: terracotta --help
+   :prompt:
+
 optimize-rasters
 ----------------
 
+.. program-output:: terracotta optimize-rasters --help
+   :prompt:
+
 ingest
 ------
 
+.. program-output:: terracotta ingest --help
+   :prompt:
+
 serve
 -----
 
+.. program-output:: terracotta serve --help
+   :prompt:
+
 connect
--------
+-------
+
+.. program-output:: terracotta connect --help
+   :prompt:
diff --git a/docs/conf.py b/docs/conf.py
@@ -43,7 +43,8 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
-    'sphinx_autodoc_typehints'
+    'sphinx_autodoc_typehints',
+    'sphinxcontrib.programoutput'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/get-started.rst b/docs/get-started.rst
@@ -0,0 +1,14 @@
+Get started
+===========
+
+Installation
+------------
+
+Creating a raster database
+--------------------------
+
+Serving data
+------------
+
+Connecting to a running Terracotta server
+-----------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
@@ -9,7 +9,9 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   tutorial
-   cli
+   get-started
    settings
+   cli
    api
+   tutorial
+   issues
diff --git a/docs/issues.rst b/docs/issues.rst
@@ -0,0 +1,21 @@
+Troubleshooting
+===============
+
+The sections below outline some common issues people encounter when
+using Terracotta. If your problem persists, `feel free to open an
+issue <https://github.com/DHI-GRAS/terracotta/issues>`__.
+
+``OSError: error while reading file`` while deploying to AWS λ
+--------------------------------------------------------------
+
+Rasterio Linux wheels are built on CentOS, which stores SSL certificates
+in ``/etc/pki/tls/certs/ca-bundle.crt``. On other Linux flavors,
+certificates may be stored in a different location. On Ubuntu, you can
+e.g. run
+
+.. code-block:: bash
+
+   $ export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
+
+to fix this issue. For more information, see
+`mapbox/rasterio#942 <https://github.com/mapbox/rasterio/issues/942>`__.
diff --git a/docs/settings.rst b/docs/settings.rst
@@ -1,5 +1,8 @@
 Configuration
 =============
 
+Available settings
+------------------
+
 .. autoclass:: terracotta.config.TerracottaSettings
    :members:
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
@@ -1,10 +1,11 @@
 Tutorials
 =========
 
-
 .. toctree::
    :maxdepth: 1
    :caption: Available Tutorials:
-
+
+   tutorials/aws
    tutorials/wsgi
-   tutorials/windows
+   tutorials/categorical
+   tutorials/windows
diff --git a/docs/tutorials/aws.rst b/docs/tutorials/aws.rst
@@ -0,0 +1,17 @@
+A serverless Terracotta deployment on AWS
+=========================================
+
+Environment setup
+-----------------
+
+Optional: Setup MySQL server on RDS
+-----------------------------------
+
+Populate data storage and create database
+-----------------------------------------
+
+Deploy via Zappa
+----------------
+
+Verify deployment
+-----------------
diff --git a/docs/tutorials/wsgi.rst b/docs/tutorials/wsgi.rst
@@ -1,5 +1,5 @@
-Deploying Terracotta with Nginx and Gunicorn
-============================================
+A traditional Terracotta deployment with Nginx and Gunicorn
+===========================================================
 
 This tutorial describes how to deploy Terracotta on a server running Ubunutu
 18.04. For this we will use Gunicorn to spin up the WSGI instance and

diff --git a/setup.py b/setup.py
@@ -1,16 +1,46 @@
 from setuptools import setup, find_packages
+from os import path
 
+here = path.abspath(path.dirname(__file__))
+
+# get the long description from the README file
+with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
+    long_description = f.read()
 
 setup(
+    # metadata
     name='terracotta',
     description='A modern XYZ tile server written in Python',
+    long_description=long_description,
+    url='https://github.com/DHI-GRAS/terracotta',
     author='Philip Graae',
     author_email='phgr@dhigroup.com',
-    packages=find_packages(),
+    keywords='xyz tileserver rasterio cloud-optimized-geotiff serverless',
+    classifiers=[
+        'Development Status :: 4 - Beta',
+        'Intended Audience :: End Users/Desktop',
+        'Intended Audience :: Science/Research',
+        'Intended Audience :: System Administrators',
+        'Topic :: Software Development :: Build Tools',
+        'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python :: 3.6',
+        'Programming Language :: Python :: 3.7',
+        'Framework :: Flask',
+        'Operating System :: Microsoft :: Windows :: Windows 10',
+        'Operating System :: MacOS :: MacOS X',
+        'Operating System :: Unix',
+        'Topic :: Internet :: WWW/HTTP :: HTTP Servers',
+        'Topic :: Internet :: WWW/HTTP :: WSGI :: Application',
+        'Topic :: Multimedia :: Graphics :: Viewers',
+        'Topic :: Scientific/Engineering :: GIS'
+    ],
+    # module
+    packages=find_packages(exclude=['docs', 'tests']),
     python_requires='>=3.6',
     use_scm_version={
         'write_to': 'terracotta/_version.py'
     },
+    # dependencies
     setup_requires=[
         'setuptools_scm',
         'setuptools_scm_git_archive',
@@ -49,23 +79,26 @@
         ],
         'docs': [
             'sphinx',
-            'sphinx_autodoc_typehints'
+            'sphinx_autodoc_typehints',
+            'sphinxcontrib-programoutput'
         ],
         'recommended': [
             'colorlog',
             'crick',
             'pymysql'
         ]
     },
+    # CLI
     entry_points='''
         [console_scripts]
         terracotta=terracotta.scripts.cli:entrypoint
     ''',
+    # package data
     include_package_data=True,
     package_data={
         'terracotta': [
             'cmaps/*_rgb.npy',  # colormaps
             'templates/*.html', 'static/*.js', 'static/*.css', 'static/images/*.png'  # preview app
         ]
-    }
+    },
 )
diff --git a/terracotta/config.py b/terracotta/config.py
@@ -16,7 +16,7 @@ class TerracottaSettings(NamedTuple):
     #: Path to database
     DRIVER_PATH: str = ''
 
-    #: Driver provider to use (sqlite, sqlite-remote, mysql; default: auto-detect)
+    #: Driver provider to use (sqlite, sqlite-remote, mysql; auto-detected by default)
     DRIVER_PROVIDER: Optional[str] = None
 
     #: Activate debug mode in Flask app
@@ -46,7 +46,7 @@ class TerracottaSettings(NamedTuple):
     #: Timeout in seconds for database connections
     DB_CONNECTION_TIMEOUT: int = 10
 
-    #: Path where cached remote SQLite databases are stored (sqlite-remote provider)
+    #: Path where cached remote SQLite databases are stored (when using sqlite-remote provider)
     REMOTE_DB_CACHE_DIR: str = os.path.join(tempfile.gettempdir(), 'terracotta')
 
     #: Time-to-live of remote database cache in seconds

diff --git a/terracotta/drivers/sqlite.py b/terracotta/drivers/sqlite.py
@@ -34,7 +34,10 @@ def convert_exceptions(msg: str) -> Iterator:
 class SQLiteDriver(RasterDriver):
     """SQLite-backed raster driver.
 
-    Thread-safe by opening a single connection per thread.
+    Note:
+
+        This driver is not thread-safe. It is not possible to connect to the database
+        outside the main thread.
 
     The SQLite database consists of 4 different tables:
 

diff --git a/terracotta/drivers/sqlite_remote.py b/terracotta/drivers/sqlite_remote.py
@@ -56,7 +56,11 @@ def _update_from_s3(remote_path: str, local_path: str) -> None:
 class RemoteSQLiteDriver(SQLiteDriver):
     """SQLite-backed raster driver, supports databases stored remotely in an S3 bucket.
 
-    This driver is read-only.
+    Note:
+
+        This driver is read-only. Any attempts to use the create, insert, or delete methods
+        will throw a NotImplementedError.
+
     """
     path: str