Merge pull request #32 from AspenWeb/docs

Basic sphinx cleanup

aspen/__init__.py

@@ -1,3 +1,77 @@
+"""
+#########
+  Aspen
+#########
+
+Aspen is a filesystem dispatch library for Python web frameworks. Instead of
+using regular expressions, decorators, or object traversal, Aspen dispatches
+HTTP requests based on the natural symmetry of URL paths and filesystem paths.
+In the `immortal words`_ of Jeff Lindsay, "so like. a web server." Exactly! ;-)
+
+.. _immortal words: https://twitter.com/progrium/status/773694289033383937
+
+This is the documentation for the development version of the core Aspen
+library, describing its filesystem dispatch behavior regardless of the web
+framework you're using it with. For instructions on configuring Aspen with a
+specific web framework, see the docs for `django-aspen`_, `Flask-Aspen`_, or
+`Pando`_. See the `project homepage`_ for an overview.
+
+.. _django-aspen: http://django.aspen.io/
+.. _Flask-aspen: http://flask.aspen.io/
+.. _Pando: http://pando.aspen.io/
+.. _project homepage: http://aspen.io/
+
+This version of Aspen has been tested with Python 2.7, 3.4, and 3.5, on both
+Ubuntu and Windows.
+
+
+**************
+ Installation
+**************
+
+Aspen is available on `GitHub`_ and on `PyPI`_::
+
+    $ pip install aspen
+
+.. _GitHub: https://github.com/AspenWeb/aspen.py
+.. _PyPI: https://pypi.python.org/pypi/aspen
+
+
+*******
+ Legal
+*******
+
+Aspen is distributed under the `MIT license`_.
+
+.. _MIT license: https://github.com/AspenWeb/aspen.py/blob/master/COPYRIGHT
+
+
+**********
+ See Also
+**********
+
+The `Keystone`_ web framework was inspired by Aspen.
+
+.. _Keystone: http://keystone.readthedocs.org/
+
+
+***********
+ Reference
+***********
+
+This is the API reference for the Aspen library.
+
+.. automodule:: aspen.simplates
+.. automodule:: aspen.http
+.. automodule:: aspen.request_processor
+.. automodule:: aspen.resources
+.. automodule:: aspen.output
+.. automodule:: aspen.configuration
+.. automodule:: aspen.exceptions
+.. automodule:: aspen.testing
+.. automodule:: aspen.utils
+
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/configuration/__init__.py

@@ -1,3 +1,13 @@
+"""
+
+:mod:`configuration`
+====================
+
+Configuration.
+
+.. automodule:: aspen.configuration.parse
+
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/configuration/parse.py

@@ -1,4 +1,8 @@
 """
+
+:mod:`parse`
+============
+
 Define parser/validators for configuration system
 
 Each of these is guaranteed to be passed a unicode object as read from the

aspen/exceptions.py

@@ -1,3 +1,9 @@
+"""
+:mod:`exceptions`
+=================
+
+Exceptions.
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/http/__init__.py

@@ -0,0 +1,12 @@
+"""
+:mod:`http`
+===========
+
+Aspen doesn't implement all of HTTP, only things related to filesystem
+dispatch.
+
+.. automodule:: aspen.http.mapping
+.. automodule:: aspen.http.request
+.. automodule:: aspen.http.resource
+
+"""

aspen/http/mapping.py

@@ -1,23 +1,29 @@
+"""
+:mod:`mapping`
+--------------
+
+This module implements a class to represent HTTP mappings.
+
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function
 from __future__ import unicode_literals
 
 
-
 NO_DEFAULT = object()
 
 
 class Mapping(dict):
-    """Base class for HTTP mappings: Path, Querystring, Headers, Cookie, Body.
+    """Base class for HTTP mappings.
 
     Mappings in HTTP differ from Python dictionaries in that they may have one
     or more values. This dictionary subclass maintains a list of values for
-    each key. However, access semantics are asymetric: subscript assignment
-    clobbers to the list, while subscript access returns the last item. Think
+    each key. However, access semantics are asymmetric: subscript assignment
+    clobbers to list, while subscript access returns the last item. Think
     about it.
 
-    WARNING: this isn't thread-safe
+    .. warning:: This isn't thread-safe.
 
     """
 

aspen/http/request.py

@@ -1,4 +1,8 @@
 """
+:mod:`request`
+--------------
+
+Aspen models the path and querystring parts of an HTTP request message.
 """
 from __future__ import absolute_import
 from __future__ import division

aspen/http/resource.py

@@ -1,4 +1,9 @@
+"""
+:mod:`resource`
+---------------
 
+This module implements classes for modeling static and dynamic HTTP resources.
+"""
 import mimeparse
 
 from ..exceptions import NegotiationFailure

aspen/output.py

@@ -1,3 +1,11 @@
+"""
+:mod:`output`
+=============
+
+Implement a class for capturing request processing output.
+
+"""
+
 class Output(object):
     body = media_type = charset = None
 

aspen/renderers.py

@@ -1,4 +1,3 @@
-
 # for backwards compatibility with aspen-renderer modules
 from .simplates.renderers import Factory, Renderer
 

aspen/request_processor/__init__.py

@@ -1,3 +1,17 @@
+"""
+:mod:`request_processor`
+========================
+
+The request processor dispatches requests to the filesystem (typecasting URL
+path variables), loads the resource from the filesystem, and then renders and
+encodes the resource. This algorithm is defined in the :mod:`algorithm` module,
+with dispatching and typecasting in additional modules.
+
+.. automodule:: aspen.request_processor.algorithm
+.. automodule:: aspen.request_processor.dispatcher
+.. automodule:: aspen.request_processor.typecasting
+
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/request_processor/algorithm.py

@@ -1,4 +1,7 @@
 """
+:mod:`algorithm`
+----------------
+
 These functions comprise the request processing functionality of Aspen.
 
 The order of functions in this module defines Aspen algorithm for request

aspen/request_processor/dispatcher.py

@@ -1,4 +1,7 @@
 """
+:mod:`dispatcher`
+-----------------
+
 Implement Aspen's filesystem dispatch algorithm.
 """
 from __future__ import absolute_import

aspen/request_processor/typecasting.py

@@ -1,5 +1,9 @@
 """
-Pluggable typecasting of virtual path values
+:mod:`typecasting`
+------------------
+
+This module implements pluggable typecasting of URL path variables.
+
 """
 from __future__ import absolute_import
 from __future__ import division

aspen/resources.py

@@ -1,4 +1,7 @@
 """
+:mod:`resources`
+================
+
 This is a registry of filesystem paths to objects representing HTTP resources.
 
 Use :py:func:`get` to use the cache, use :py:func:`load` to circumvent it.

aspen/simplates/__init__.py

@@ -0,0 +1,36 @@
+"""
+:mod:`simplates`
+================
+
+The simplates module implements Aspen's file format, simplates (*.spt).
+Simplates combine request processing logic (think: Rails controller, or Django
+view) with template code in one file. Here's an example::
+
+    # Python syntax. Runs once on startup.
+    import random
+
+    [----]
+    # Python syntax. Runs once per request..
+    program = request.qs['program']
+    excitement = '!' * random.randint(1, 10)
+
+    # One of the following is used on each request, based on content type
+    # negotiation. The syntax depends on the renderer.
+
+    [----] text/html via jinja2
+    <h1>Greetings, {{ program }}{{ excitement }}</h1>
+
+    [----] text/plain via stdlib_format
+    Greetings, {program}{excitement}
+
+    [----] application/json via json_dump
+    { "program": program
+    , "excitement": excitement
+     }
+
+
+.. automodule:: aspen.simplates.renderers
+.. automodule:: aspen.simplates.pagination
+.. automodule:: aspen.simplates.json_
+
+"""

aspen/simplates/json_.py

@@ -1,3 +1,7 @@
+"""
+:mod:`json_`
+------------
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/pagination.py

@@ -1,3 +1,7 @@
+"""
+:mod:`pagination`
+-----------------
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/renderers/__init__.py

@@ -1,4 +1,7 @@
 """
+:mod:`renderers`
+----------------
+
 This module implements pluggable content rendering.
 
 Negotiated and rendered resources have content pages the bytes for which are
@@ -68,6 +71,12 @@ class CheeseFactory(Factory):
 machinery is inadequate for some reason let's evolve the machinery so all
 renderers behave consistently for users. Thanks.
 
+.. automodule:: aspen.simplates.renderers.jsonp_dump
+.. automodule:: aspen.simplates.renderers.json_dump
+.. automodule:: aspen.simplates.renderers.stdlib_format
+.. automodule:: aspen.simplates.renderers.stdlib_percent
+.. automodule:: aspen.simplates.renderers.stdlib_template
+
 """
 from __future__ import absolute_import
 from __future__ import division

aspen/simplates/renderers/json_dump.py

@@ -1,3 +1,7 @@
+"""
+:mod:`json_dump`
+^^^^^^^^^^^^^^^^
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/renderers/jsonp_dump.py

@@ -1,3 +1,7 @@
+"""
+:mod:`jsonp_dump`
+^^^^^^^^^^^^^^^^^^
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/renderers/stdlib_format.py

@@ -1,3 +1,7 @@
+"""
+:mod:`stdlib_format`
+^^^^^^^^^^^^^^^^^^^^
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/renderers/stdlib_percent.py

@@ -1,3 +1,7 @@
+"""
+:mod:`stdlib_percent`
+^^^^^^^^^^^^^^^^^^^^^
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/renderers/stdlib_template.py

@@ -1,3 +1,7 @@
+"""
+:mod:`stdlib_template`
+^^^^^^^^^^^^^^^^^^^^^^
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/simplate.py

@@ -1,3 +1,7 @@
+"""
+:mod:`simplate`
+---------------
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/testing.py

@@ -1,3 +1,10 @@
+"""
+:mod:`testing`
+==============
+
+This module provides helpers for testing applications that use Aspen.
+
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/utils.py

@@ -1,3 +1,11 @@
+"""
+:mod:`utils`
+============
+
+This module collects a few random bits that should be placed somewhere that
+makes more sense.
+
+"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function