add a front matter

Change-Id: I20b2e4edd099aaa9d6a851111b71e4e8379b0554

README.rst

@@ -10,6 +10,19 @@ asyncio compatible approaches, but allowing intermediary code to remain
 completely unchanged.  Its primary use is to support code that is cross-compatible
 with asyncio and non-asyncio runtime environments.
 
+The entire API demonstrated in three lines, where a non ``async`` def can
+be invoked in an asyncio context and can then call upon real awaitables
+directly::
+
+    import asyncio
+
+    import awaitlet
+
+    def asyncio_sleep():
+        return awaitlet.awaitlet(asyncio.sleep(5, result='hello'))
+
+    print(asyncio.run(awaitlet.async_def(asyncio_sleep)))
+
 awaitlet is intentionally fully compatible with SQLAlchemy's asyncio mediation
 layer, and includes API patterns for:
 

docs/build/front.rst

@@ -0,0 +1,59 @@
+============
+Front Matter
+============
+
+Information about the awaitlet project.
+
+Project Homepage
+================
+
+awaitlet is hosted on GitHub at https://github.com/sqlalchemy/awaitlet under the SQLAlchemy organization.
+
+Releases and project status are available on Pypi at https://pypi.python.org/pypi/awaitlet.
+
+The most recent published version of this documentation should be at https://awaitlet.sqlalchemy.org.
+
+
+.. _installation:
+
+Installation
+============
+
+Awaitlet is available on pypi under the name ``awaitlet``::
+
+    $ pip install awaitlet
+
+
+Dependencies
+------------
+
+awaitlet's sole dependency is the `greenlet <https://pypi.org/project/greenlet/>`_
+library.  This is a widely used library that allows for coroutines in Python.
+
+Greenlet is written in C.  While the package has binary releases available for
+many platforms available, there may not be binary releases pre-built for some
+architectures in some cases, in which case the environment will need Python
+native extension build tools and dependencies to be present.     Greenlet also
+may not be functional on pre-release cPython interpreters, as it
+typically requires updates to be compatible with newer cPython releases.
+
+
+Community
+=========
+
+awaitlet is developed by `Mike Bayer <http://techspot.zzzeek.org>`_, and is
+part of the SQLAlchemy_ project.
+
+User issues, discussion of potential bugs and features are most easily
+discussed using `GitHub Discussions <https://github.com/sqlalchemy/awaitlet/discussions/>`_.
+
+.. _bugs:
+
+Bugs
+====
+
+Bugs and feature enhancements to awaitlet should be reported on the `GitHub
+issue tracker
+<https://github.com/sqlalchemy/awaitlet/issues/>`_.
+
+.. _SQLAlchemy: https://www.sqlalchemy.org

docs/build/index.rst

@@ -36,8 +36,8 @@ API patterns for:
   SQLAlchemy's synchronous API for database access
 
 The two functions provided are :func:`.async_def` and :func:`.awaitlet`.  Using
-these, we can create an asyncio program using intermediary defs that do not use the `async`
-or `await` keywords, but instead use functions::
+these, we can create an asyncio program using intermediary defs that do not use the ``async``
+or ``await`` keywords, but instead use functions::
 
    import asyncio
 
@@ -74,6 +74,7 @@ Contents in this Document
 .. toctree::
    :maxdepth: 2
 
+   front
    synopsis
    sqlalchemy
    api