fix Sphinx docs

aspen/__init__.py

@@ -1,69 +1,8 @@
-"""This is Aspen, a dynamic Jekyll for Python.
-
-
-Installation
-------------
-
-:py:mod:`aspen` is available on `GitHub`_ and on `PyPI`_::
-
- $ pip install aspen
-
-We `test <https://travis-ci.org/gittip/aspen-python>`_ against Python 2.7.
-
-:py:mod:`aspen` is in `MIT-licensed`_.
-
-.. _github: https://github.com/gittip/aspen-python
-.. _pypi: https://pypi.python.org/pypi/aspen
-.. _MIT-licensed: http://opensource.org/licenses/MIT
-
-
-Quick Start
------------
-
-Given: `POSIX <http://en.wikipedia.org/wiki/POSIX#POSIX-oriented_operating_systems>`_
-and `virtualenv <http://pypi.python.org/pypi/virtualenv>`_
-
-Step 1: Make a sandbox:
-
- $ virtualenv foo
- $ cd foo
- $ . bin/activate</pre>
- ::
-
-Step 2: Install `aspen from PyPI <http://pypi.python.org/pypi/aspen>`_:
-
- (foo)$ pip install aspen
- blah
- blah
- blah
- ::
-
-Step 3: Create a website root:
-
- (foo)$ mkdir www
- (foo)$ cd www</pre>
- ::
-
-Step 4: Create a web page, and start aspen inside it:
-
- (foo)$ echo Greetings, program! > index.html.spt
- (foo)$ aspen
- Greetings, program! Welcome to port 8080.
- ::
-
-Step 5: Check `localhost http://localhost:8080`_ for your new page!
-
- .. image:: greetings-program.png
-
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function
 from __future__ import unicode_literals
 
 import sys
-import pkg_resources
 
-dist = pkg_resources.get_distribution('aspen')
-__version__ = dist.version
 WINDOWS = sys.platform[:3] == 'win'

aspen/backcompat.py

@@ -1,7 +1,3 @@
-"""
-aspen.backcompat
-++++++++++++++++
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/exceptions.py

@@ -1,9 +1,3 @@
-"""
-aspen.exceptions
-++++++++++++++++
-
-Exceptions used by Aspen
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/http/__init__.py

@@ -1,8 +0,0 @@
-"""
-aspen.http
-++++++++++
-"""
-from __future__ import absolute_import
-from __future__ import division
-from __future__ import print_function
-from __future__ import unicode_literals

aspen/http/mapping.py

@@ -1,7 +1,3 @@
-"""
-aspen.http.mapping
-~~~~~~~~~~~~~~~~~~
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/http/request.py

@@ -25,9 +25,6 @@ def __new__(cls, value, params):
 
 class Path(Mapping):
  """Represent the path of a resource.
-
- This is populated by aspen.gauntlet.virtual_paths.
-
  """
 
  def __init__(self, raw):

aspen/request_processor/__init__.py

@@ -1,7 +1,3 @@
-"""
-aspen.request_processor
-+++++++++++++++++++++++
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/request_processor/algorithm.py

@@ -1,7 +1,4 @@
 """
-aspen.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,7 +1,4 @@
 """
-aspen.dispatcher
-++++++++++++++++
-
 Implement Aspen's filesystem dispatch algorithm.
 """
 from __future__ import absolute_import

aspen/request_processor/parse.py

@@ -1,7 +1,4 @@
 """
-aspen.configuration.parse
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
 Define parser/validators for configuration system
 
 Each of these is guaranteed to be passed a unicode object as read from the

aspen/request_processor/typecasting.py

@@ -1,9 +1,5 @@
 """
-aspen.typecasting
-+++++++++++++++++
-
 Pluggable typecasting of virtual path values
-
 """
 from __future__ import absolute_import
 from __future__ import division

aspen/resources.py

@@ -1,7 +1,4 @@
 """
-aspen.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/json_.py

@@ -1,7 +1,3 @@
-"""
-aspen.json
-++++++++++
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/pagination.py

@@ -1,7 +1,3 @@
-"""
-aspen.resources.pagination
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/renderers/__init__.py

@@ -1,9 +1,6 @@
 """
-aspen.simplates.renderers
-+++++++++++++++++++++++++
-
 This module implements pluggable content rendering.
- #
+
 See user docs here:
 
  http://aspen.io/simplates/rendered/
@@ -14,23 +11,23 @@
 Template resources derive their media type from the file extension. Negotiated
 resources have no file extension by definition, so they specify the media type
 of their content pages in the resource itself, on the so-called "specline" of
-each content page, like so:
+each content page, like so::
 
- ^L
- ^L text/plain
+ [---]
+ [---] text/plain
  Greetings, program!
- ^L text/html
+ [---] text/html
  <h1>Greetings, program!</h1>
 
 
 A Renderer is instantiated by a Factory, which is a class that is itself
-instantied with one argument:
+instantied with one argument::
 
  configuration an Aspen configuration object
 
 
 Instances of each Renderer subclass are callables that take five arguments and
-return a function (confused yet?). The five arguments are:
+return a function (confused yet?). The five arguments are::
 
  factory the Factory creating this object
  filepath the filesystem path of the resource in question
@@ -43,7 +40,7 @@
 returns a bytestring of rendered content. The heavy lifting is done in the
 render_content method.
 
-Here's how to implement and register your own renderer:
+Here's how to implement and register your own renderer::
 
  from aspen.simplates.renderers import Renderer, Factory
 
@@ -58,13 +55,13 @@ class CheeseFactory(Factory):
 
 
 Put that in your startup script. Now you can use it in a negotiated or rendered
-resource:
+resource::
 
- ^L #!excited-about-cheese
+ [---] via excited-about-cheese
  I like cheese!
 
 
-Out will come:
+Out will come::
 
  I like CHEESE!!!!!!!
 
@@ -160,7 +157,7 @@ def compile(self, filepath, raw):
  def render_content(self, context):
  """Override. Context is a dict.
 
- You can use these attributes:
+ You can use these attributes::
 
  self.raw the raw bytes of the content page
  self.compiled the result of self.compile (generally a template in

aspen/simplates/renderers/json_dump.py

@@ -1,7 +1,3 @@
-"""
-aspen.simplates.renderers.json_dump
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/renderers/jsonp_dump.py

@@ -1,7 +1,3 @@
-"""
-aspen.simplates.renderers.jsonp_dump
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/renderers/stdlib_format.py

@@ -1,7 +1,3 @@
-"""
-aspen.simplates.renderers.stdlib_format
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/renderers/stdlib_percent.py

@@ -1,7 +1,3 @@
-"""
-aspen.simplates.renderers.stdlib_percent
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/renderers/stdlib_template.py

@@ -1,7 +1,3 @@
-"""
-aspen.simplates.renderers.stdlib_template
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/simplates/simplate.py

@@ -1,7 +1,3 @@
-"""
-aspen.resources.dynamic_resource
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function
@@ -150,12 +146,12 @@ def best_match(self, accept, default=None):
 
  def render(self, accept, context):
  """
- get the response to a request for this page
+ Get the response to a request for this page::
 
- accept - an HTTP Accept: header asking for this page
- context - a dict of execution context values you wish to supply
- * Note that these are overriden by values that are carried
- over from the execution of the zeroth page
+  accept - an HTTP Accept: header asking for this page
+  context - a dict of execution context values you wish to supply
+  * Note that these are overriden by values that are carried
+  over from the execution of the zeroth page
  """
 
  # copy the state dict to avoid accidentally mutating it
@@ -184,7 +180,7 @@ def parse_into_pages(self, decoded):
 
  If there's one page, it's a template.
  If there's more than one page, the first page is always python and the last is always a template.
- If there's more than two pages, the second page is python _unless it has a specline_, which makes it a template
+ If there's more than two pages, the second page is python *unless it has a specline*, which makes it a template
 
  """
 

aspen/testing.py

@@ -1,7 +1,3 @@
-"""
-aspen.testing
-+++++++++++++
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function

aspen/utils.py

@@ -1,7 +1,3 @@
-"""
-aspen.utils
-+++++++++++
-"""
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function
@@ -76,7 +72,7 @@ def by_regex(regex_tuples, default=True):
  requested URI, then the flow is applied or not based on if filter? is True
  or False.
 
- For example:
+ For example::
 
  from aspen.flows.filter import by_regex