Commits

James Mills committed 1081893 Merge

Merged with py2 branch

Comments (0)

Files changed (51)

 	@find . -name '*~' -delete
 
 docs:
-	@make -C docs html
+	@make -C docs clean html
 
 graph:
 	@sfood circuits -i -I tests -d -u 2> /dev/null | sfood-graph | dot -Tps | ps2pdf - > circuits.pdf

circuits/__init__.py

 
 __author__ = "James Mills"
 __date__ = "12th February 2011"
-__version__ = "1.5"
+__version__ = "1.6"
 
 from circuits.core import handler, BaseComponent, Component, Event
 from circuits.core import future, Pool, Task, Worker

circuits/core/handlers.py

     new Component and turn them into Event Handlers by applying the
     @handlers decorator on them. This is done for all methods defined in
     the Component that:
-     - Do not start with a single '_'. or
-     - Have previously been decorated with the @handlers decorator
+    - Do not start with a single '_'. or
+    - Have previously been decorated with the @handlers decorator
     """
 
     def __init__(cls, name, bases, dct):

circuits/core/pollers.py

 
 This module contains Poller components that enable polling of file or socket
 descriptors for read/write events. Pollers:
-   - Select
-   - Poll
-   - EPoll
+- Select
+- Poll
+- EPoll
 """
 
 from errno import *

circuits/net/protocols/line.py

     to be used in conjunction with components that expose a Read Event on
     a "read" channel with only one argument (data). Some builtin components
     that expose such events are:
-     * circuits.net.sockets.TCPClient
-     * circuits.io.File
+    - circuits.net.sockets.TCPClient
+    - circuits.io.File
 
     The second mode of operation works with circuits.net.sockets.Server
     components such as TCPServer, UNIXServer, etc. It's expected that

circuits/net/sockets.py

 
 class Connect(Event):
     """Connect Event
-
+    
     This Event is sent when a new client connection has arrived on a server.
     This event is also used for client's to initiate a new connection to
     a remote host.
-
-    @note: This event is used for both Client and Server Components.
-
+    
+    .. note ::
+       
+       This event is used for both Client and Server Components.
+    
     :param args:  Client: (host, port) Server: (sock, host, port)
     :type  args: tuple
-
+    
     :param kwargs: Client: (ssl)
     :type  kwargs: dict
     """

circuits/web/dispatchers/virtualhosts.py

     This can be useful when running multiple sites within one server.
     It allows several domains to point to different parts of a single
     website structure. For example:
-     - http://www.domain.example      -> /
-     - http://www.domain2.example     -> /domain2
-     - http://www.domain2.example:443 -> /secure
+    - http://www.domain.example      -> /
+    - http://www.domain2.example     -> /domain2
+    - http://www.domain2.example:443 -> /secure
 
     :param domains: a dict of {host header value: virtual prefix} pairs.
     :type  domains: dict

circuits/web/tools.py

     
     If 'secs' is zero, the 'Expires' header is set one year in the past, and
     the following "cache prevention" headers are also set:
-       - 'Pragma': 'no-cache'
-       - 'Cache-Control': 'no-cache, must-revalidate'
+    - 'Pragma': 'no-cache'
+    - 'Cache-Control': 'no-cache, must-revalidate'
     
     If 'force' is False (the default), the following headers are checked:
     'Etag', 'Last-Modified', 'Age', 'Expires'. If any are already present,
 
 clean:
 	-rm -rf $(BUILDDIR)/*
-	rm -rf source/api/
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

docs/source/_static/tracsphinx.css

+/* Trac specific styling */
+
+@import url("sphinxdoc.css");
+
+/* Structure */
+
+div.footer {
+    background-color: #4b4d4d;
+    text-align: center;
+}
+
+div.bodywrapper {
+    border-right: none;
+}
+
+/* Sidebar */
+
+div.sphinxsidebarwrapper {
+    -moz-box-shadow: 2px 2px 7px 0 grey;
+    -webkit-box-shadow: 2px 2px 7px 0 grey;
+    box-shadow: 2px 2px 7px 0 grey;
+    padding: 0 0 1px .4em;
+}
+
+div.sphinxsidebar h3 a,
+div.sphinxsidebar h4 a {
+    color: #b00;
+}
+
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+    padding: 0;
+    color: black;
+}
+
+div.sphinxsidebar h3, div.sphinxsidebar h4 {
+    background: none;
+    border: none;
+    border-bottom: 1px solid #ddd;
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #d7d7d7;
+}
+
+p.searchtip {
+    font-size: 90%;
+    color: #999;
+}
+
+/* Navigation */
+
+div.related ul li a { color: #b00 }
+div.related ul li a:hover {
+    color: #b00;
+}
+
+/* Content */
+
+body {
+    font: normal 13px Verdana,Arial,'Bitstream Vera Sans',Helvetica,sans-serif;
+    background-color: #4b4d4d;
+    border: none;
+    border-top: 1px solid #aaa;
+}
+h1, h2, h3, h4 {
+    font-family: Arial,Verdana,'Bitstream Vera Sans',Helvetica,sans-serif;
+    font-weight: bold;
+    letter-spacing: -0.018em;
+    page-break-after: avoid;
+}
+
+h1 { color: #555 }
+h2 { border-bottom: 1px solid #ddd }
+
+div.body a { text-decoration: none }
+a, a tt { color: #b00 }
+a:visited, a:visited tt { color: #800 }
+
+:link:hover, :visited:hover,
+a:link:hover tt, a:visited:hover tt {
+    background-color: #eee; 
+    color: #555;
+}
+
+a.headerlink, a.headerlink:hover {
+    color: #d7d7d7 !important; 
+    font-size: .8em;
+    font-weight: normal;
+    vertical-align: text-top;
+    margin: 0;
+    padding: .5em;
+}
+a.headerlink:hover {
+    background: none;
+}
+
+div.body h1 a, div.body h2 a, div.body h3 a,
+div.body h4 a, div.body h5 a, div.body h6 a {
+    color: #d7d7d7 !important;
+}
+
+dl.class {
+    -moz-box-shadow: 1px 1px 6px 0 #888;
+    -webkit-box-shadow: 1px 1px 6px 0 #888;
+    box-shadow:  1px 1px 6px 0 #888;
+    padding: .5em;
+}
+dl.function {
+    margin-bottom: 24px;
+}
+
+dl.class > dt, dl.function > dt {
+    border-bottom: 1px solid #ddd;
+}
+
+th.field-name {
+    white-space: nowrap;
+    font-size: 90%;
+    color: #555;
+}
+
+td.field-body > ul {
+    list-style-type: square;
+}
+
+td.field-body > ul > li > strong {
+    font-weight: normal;
+    font-style: italic;
+}
+
+/* Admonitions */
+
+div.admonition p.admonition-title, div.warning p.admonition-title {
+    background: none;
+    color: #555;
+    border: none;
+}
+
+div.admonition {
+    background: none;
+    border: none;
+    border-left: 2px solid #acc;
+}    
+
+div.warning {
+    background: none;
+    border: none;
+    border-left: 3px solid #c33;
+}    
+
+/* Search */
+
+dl:target, dt:target, .highlighted { background-color: #ffa }
+

docs/source/changelog.rst

-Change Log
-==========
-
-
-1.4 (20110212)
---------------
-
-
-Features
-........
-
-- circuits.core: **NEW** workers and futures modules.
-  This adds thread and process concurrency support to circuits.
-
-- circuits.web: **NEW** Web Client for circuits.web
-
-- circuits.core: Implemented a basic handler cache on the Manager.
-  Improves overall performance of circuits by as much as ~33%
-
-- circuits.core: Passing keyword argument `sleep` to `Manager.start(...)`
-  or `Manager.run(...)` is now deprecated.
-
-
-Bug Fixes
-.........
-
-- circuits.app: Fixed :bbissue:`14`
-
-- circuits.web: Fixed streaming support for `wsgi.Gateway`
-
-- circuits.tools: Catch InvocationError from environments where pydot is
-  installed but no graphviz executable (*Mac OS X*)
-
-- circuits.web: Fixed a bug where if no "Content-Length" was provided
-  (*By Google Chrom's WebSocket*) but a body was given `circuits.web`
-  would expect more data to be given.
-
-- circuits.net: Catch gaierror exceptions on calls to `gethostbyname()`
-  to determine where we're binding.
-  Fix for misconfigured desktop environments.
-
-- circuits.core: Ignore `ValueError` raised if we can't install signal
-  handlers such as when running as a Windows Service.
-
-- circuits.web: Fixed -m/--multiprocessing mode and modified to accept a
-  no. of processes to start (circuits.web binary/script).
-
-
-1.3.3 (20110205)
-----------------
-
-
-Features
-........
-
-- circuits.core.workers: Add import of cpu_count/cpuCount as cpus from the
-  respective multiprocessing/processing modules
-
-- circuits.web.app: Two apps newly added. WebConsole and MemoryMonitor
-  See: http://codepad.org/iQwBgfdM for an example
-
-- circuits.core.debugger: If the Debugger isn't logging to a file or logger
-  (*we're logging to sys.stderr*) it's useful to restrict the output for
-  common terminal widths of 80.
-
-  - circuits.core.debugger: Make chopping long lines when logging to sys.stderr
-    optional with kwarg ``chop`` (**Default:** ``False``).
-
-- circuits.web.errors: Make traceback available on the HTTPError Event Object
-  as self.traceback
-
-
-Bug Fixes
-.........
-
-- circuits.web.main: Only start multiple processes if multiprocessing is
-  actually available
-
-- circuits.core.pollers: Ignore IOError of EINTR (4)
-
-- circuits.app: Fixed a bug with loading a Logger instance and loading the
-  Config instance (*``circuits.app needs`` to be refactored*)
-
-
-Examples
-........
-
-- examples/web/jsonserializer.py: New example showing how to build a simple
-  request filter that intercepts the return values of request handlers before
-  they get added to the response body
-
-- examples/web/filtering.py: Fixed example
-
-
-1.3.2 (20110201)
-----------------
-
-
-Bug Fixes
-.........
-
-- Fixed several Python 2.5 incompatibilities.
-
-- circuits.web.wsgi: Fixed a bug with writing to the ``request.body``.
-  (Forgot to rewing the ``StringIO`` instnace after writing to it)
-
-
-1.3.1 (20110131)
-----------------
-
-
-Documentation
-.............
-
-- Fixed documentation generation
-
-
-Features
-........
-
-- circuits.core.manager: Deprecated the use of the sleep parameter/argument
-  in ``Manager.start(...)`` and ``Manager.run(...)`` in favor of sleeping
-  for the specified ``circuits.core.manager.TIMEOUT`` when/iif there are no
-  tick functions to process (eg: Timer, pollers, etc)
-
-  -- If aftering processing **Tick Functions** there are no resulting
-     events to process then a sleep will occur for ``circuits.core.TIMEOUT``
-     seconds.
-
-- circuits.core.Manager: Call ``self.stop`` right at the end of normal
-  termination for script-like systems (eg: examples/cat.py)
-
-- circuits.core.Manager: If a KeyboardInterrupt or SystemExit exception
-  is raised during a **Tick Function**, then re-raise it.
-
-
-Bug Fixes
-.........
-
-- circuits.web.http: Fixed a bug with HTTP streaming
-
-- circuits.io: Fixed exceptions not being caught during shutdown
-
-- tests.core.test_bridge: Fixed and passing again :)
-
-- circuits.web.wsgi: Fixed a bug discovered when trying to deploy a
-  circuits.web WSGI Application using the uwsgi server. In the case of
-  an empty request body from the client being passed thorugh uwsgi to
-  circuits.web - No Content-Length would be provided, but also any attempt
-  to read from wsgi.input would block causing uwsgi to timeout

docs/source/conf.py

 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage',
-        'sphinx.ext.autosummary', 'sphinxcontrib.bitbucket']
+extensions = []
 
 bitbucket_project_url = 'https://bitbucket.org/prologic/circuits'
 
 # General information about the project.
 project = u'circuits'
 copyright = u'2004-2011, James Mills'
+url = "http://bitbucket.org/prologic/circuits/"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '1.5'
+version = '1.6'
 # The full version, including alpha/beta/rc tags.
-release = '1.5'
+release = '1.6'
+
+# Devel or Release mode for the documentation (if devel, include TODOs,
+# can also be used in conditionals: .. ifconfig :: devel)
+devel = True
+
+if devel:
+    release += "dev"
+
+# -- Autodoc
+
+extensions.append('sphinx.ext.autodoc')
+
+autoclass_content = 'both'
+autodoc_member_order = 'bysource'
+
+# -- Conditional content (see setup() below)
+extensions.append('sphinx.ext.ifconfig')
+
+# -- Keep track of :todo: items
+extensions.append('sphinx.ext.todo')
+
+todo_include_todos = devel
+
+# -- link to bitbucket issues
+
+extensions.append('sphinxcontrib.bitbucket')
+
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'trac'
 
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
+html_theme = 'sphinxdoc'
+html_style = 'tracsphinx.css'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # If false, no module index is generated.
 #latex_use_modindex = True
 
+def setup(app):
+    # ifconfig variables
+    app.add_config_value('devel', '', True)
+
 # hghooks: no-pyflakes no-pep8

docs/source/dev/bugs.rst

+Reporting Bugs
+==============
+
+Found a new bug with circuits ? Great! Here's how you file a new bug
+report so that we can fix the problem in a timely manner:
+
+.. todo :: flesh this out

docs/source/dev/contributing.rst

+Contributing to circuits
+========================
+
+Here's how you can contribute to circuits
+
+.. todo :: flesh this out

docs/source/dev/index.rst

+Developer Docs
+==============
+
+So, you'd like to contribute to circuits ins some way ? Got a bug report ?
+Having problems running the examples ? Having problems getting circuits
+working in your environment / platform ?
+
+Excellent.  Here's what you need to know.
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   contributing
+   testing
+   bugs

docs/source/dev/introduction.rst

+Development Introduction
+========================
+
+Here's how we do things in circuits...
+
+.. todo :: flesh this out

docs/source/dev/testing.rst

+Testing
+=======
+
+Here's how we do testing in circutis:
+
+.. todo :: flesh this out

docs/source/downloading.rst

-Downloading
-===========
-
-Latest Stable Release
----------------------
-
-The latest stable releases can be downloaded from the
-`Downloads <http://bitbucket.org/prologic/circuits/downloads/>`_ page.
-
-Latest Development Source Code
-------------------------------
-
-We use `Mercurial <http://mercurial.selenic.com/>`_ for source control
-and code sharing.
-
-The latest development branch can be cloned using the following command:
-
-.. code-block:: sh
-   
-   $ hg clone http://bitbucket.org/prologic/circuits/
-   
-For further instructions on how to use Mercurial, please refer to the
-`Mercurial Book <http://mercurial.selenic.com/wiki/MercurialBook>`_.

docs/source/examples.rst

-Examples
-========
-
-.. toctree::
-   :maxdepth: 2
-
-   examples/echoserver
-   examples/telnet
-   examples/ircbot
-   examples/web

docs/source/examples/echoserver.py

-#!/usr/bin/env python
-
-from circuits.net.sockets import TCPServer, Write
-
-class EchoServer(TCPServer):
-
-    def read(self, sock, data):
-        self.push(Write(sock, data))
-
-EchoServer(8000).run()

docs/source/examples/echoserver.rst

-Echo Server Example
-===================
-
-:download:`echoserver.py <echoserver.py>`
-
-.. literalinclude:: echoserver.py
-   :language: python
-   :linenos:

docs/source/examples/helloworld.py

-#!/usr/bin/env python
-
-from circuits import Event, Component
-
-class Hello(Event):
-    """Hello Event"""
-
-    end = "goodbye",
-
-class App(Component):
-
-    def started(self, component, mode):
-        self.push(Hello())
-
-    def hello(self):
-        print "Hello World!"
-
-    def goodbye(self, e, handler, v):
-        print "Goodbye World!"
-        print "Event:", e
-        print "Handler", handler
-        print "Return Value:", v
-        raise SystemExit, 0
-
-App().run()

docs/source/examples/ircbot.py

-#!/usr/bin/env python
-
-from circuits import Component
-from circuits.net.sockets import TCPClient, Connect
-from circuits.net.protocols.irc import IRC, Message, User, Nick
-
-class Bot(Component):
-
-    def __init__(self, host, port=6667, channel=None):
-        super(Bot, self).__init__(channel=channel)
-
-        self += TCPClient(channel=channel) + IRC(channel=channel)
-        self.push(Connect(host, port))
-
-    def connected(self, host, port):
-        self.push(User("test", host, host, "Test Bot"), "USER")
-        self.push(Nick("test"), "NICK")
-
-    def numeric(self, source, target, numeric, args, message):
-        if numeric == 433:
-            self.push(Nick("%s_" % args), "NICK")
-
-    def message(self, source, target, message):
-        self.push(Message(source[0], message), "PRIVMSG")
-
-Bot("irc.freenode.net", channel="bot").run()

docs/source/examples/ircbot.rst

-IRC Bot Example
-===============
-
-:download:`ircbot.py <ircbot.py>`
-
-.. literalinclude:: ircbot.py
-   :language: python
-   :linenos:

docs/source/examples/telnet.py

-#!/usr/bin/env python
-
-import os
-import optparse
-from socket import gethostname
- 
-from circuits.io import stdin
-from circuits import handler, Component
-from circuits import __version__ as systemVersion
-from circuits.net.sockets import TCPClient, UNIXClient, Connect, Write
-
-USAGE = "%prog [options] host [port]"
-VERSION = "%prog v" + systemVersion
-
-def parse_options():
-    parser = optparse.OptionParser(usage=USAGE, version=VERSION)
-   
-    opts, args = parser.parse_args()
-   
-    if len(args) < 1:
-        parser.print_help()
-        raise SystemExit, 1
-   
-    return opts, args
-   
-class Telnet(Component):
-   
-    channel = "telnet"
-
-    def __init__(self, *args):
-        super(Telnet, self).__init__()
-   
-        if len(args) == 1:
-            if os.path.exists(args[0]):
-                self += UNIXClient(channel=self.channel)
-                host = dest = port = args[0]
-                dest = (dest,)
-            else:
-                raise OSError("Path %s not found" % args[0])
-        else:
-            self += TCPClient(channel=self.channel)
-            host, port = args
-            port = int(port)
-            dest = host, port
-   
-        print "Trying %s ..." % host
-        self.push(Connect(*dest), "connect")
-   
-    def connected(self, host, port=None):
-        print "Connected to %s" % host
-   
-    def error(self, *args):
-        if len(args) == 3:
-            type, value, traceback = args
-        else:
-            value = args[0]
-            type = type(value)
-            traceback = None
-   
-        print "ERROR: %s" % value
-   
-    def read(self, data):
-        print data.strip()
-   
-    @handler("read", target="stdin")
-    def stdin_read(self, data):
-        self.push(Write(data), "write")
-   
-opts, args = parse_options()
-(Telnet(*args) + stdin).run()

docs/source/examples/telnet.rst

-Telnet Client Example
-=====================
-
-:download:`telnet.py <telnet.py>`
-
-.. literalinclude:: telnet.py
-   :language: python
-   :linenos:

docs/source/examples/web.py

-#!/usr/bin/env python
-   
-from circuits.web import Server, Controller
-
-class Root(Controller):
-
-    def index(self):
-        return "Hello World!"
-
-(Server(8000) + Root()).run()

docs/source/examples/web.rst

-Web Server Example
-==================
-
-:download:`web.py <web.py>`
-
-.. literalinclude:: web.py
-   :language: python
-   :linenos:

docs/source/gettingstarted.rst

-Getting Started
-===============
-
-.. toctree::
-   :maxdepth: 2
-
-   quickstart
-   downloading
-   installing

docs/source/glossary.rst

+========
+Glossary
+========
+
+.. glossary::
+   :sorted:
+
+   VCS
+      Version Control System, what you use for versioning your source code

docs/source/index.rst

-.. circuits documentation master file, created by
-   sphinx-quickstart on Thu Feb  4 09:44:50 2010.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+================================
+circuits |version| Documentation
+================================
 
-Introduction
-============
-
-.. include:: ../../README.rst
+:Release: |release|
+:Date: |today|
 
 Contents
 ========
 
 .. toctree::
-   :maxdepth: 2
-   
+   :maxdepth: 1
+
    foreword
    features
-   changelog
-   gettingstarted
+   start/index
+   introduction
    tutorial
-   manual
-   examples
-   web
+   web/index
+   api/index
+   dev/index
+
+.. toctree::
+   :hidden:
+
+   glossary
+   users
+
+.. ifconfig:: devel
+
+   .. toctree::
+      :hidden:
+
+      todo
+
 
 Indices and tables
 ==================
 
-* :ref:`genindex`
+* :ref:`General Index <genindex>`
 * :ref:`modindex`
 * :ref:`search`
+* :doc:`glossary`
+
+.. ifconfig:: devel
+
+   * :doc:`todo`
+

docs/source/installing.rst

-Installing
-==========
-
-If you have not installed circuits via the the
-`setuptools <http://pypi.python.org/pypi/setuptools>`_ easy_install tool,
-then the following installation instructions will apply to you. Either
-you've downloaded a source package or cloned the development repository.
-
-Installing from a Source Package
---------------------------------
-
-.. code-block:: sh
-
-   $ python setup.py install
-
-For other installation options see:
-
-.. code-block:: sh
-
-   $ python setup.py --help install
-
-Installing from the Development Repository
-------------------------------------------
-
-If you have cloned the development repository, it is recommended that you
-use setuptools and use the following command:
-
-.. code-block:: sh
-
-   $ python setup.py build develop
-
-**NB:** The "build" command is required when installing from the development
-repository (*build creates the version file which is built dynamically*).
-
-This will allow you to regularly update your copy of the circuits development
-repository by simply performing the following in the circuits working directory:
-
-.. code-block:: sh
-
-   $ hg pull -u
-
-**NB**: You do not need to reinstall if you have installed with setuptools via
-the circuits repository and used setuptools to install in "develop" mode.

docs/source/introduction.rst

+Introduction
+============
+

docs/source/manual.rst

-Manual
-======
-
-This is the in-depth circuits manual used as a reference guide and details
-into the core features and functionality of circuits.
-
-.. toctree::
-   :maxdepth: 1
-
-   manual/manager
-   manual/components
-   manual/handlers
-   manual/events
-   manual/values
-   manual/futures
-   manual/workers

docs/source/manual/components.rst

-Components
-==========
-

docs/source/manual/events.rst

-Events
-======
-

docs/source/manual/futures.rst

-Futures
-=======
-

docs/source/manual/handlers.rst

-Handlers
-========
-

docs/source/manual/manager.rst

-Manager
-=======
-

docs/source/manual/values.rst

-Values
-======
-

docs/source/manual/workers.rst

-Workers
-=======
-

docs/source/quickstart.rst

-Quick Start Guide
-=================
-
-The easiest way to download and install circuits is to use the
-`setuptools <http://pypi.python.org/pypi/setuptools>`_ easy_install tool:
-
-.. code-block:: sh
-   
-   $ easy_install circuits
-   
-
-Now that you have successfully downloaded and installed circuits, let's
-test that circuits is properly installed and working.
-
-First, let's check the installed version:
-
-.. code-block:: python
-   
-   >>> import circuits
-   >>> print circuits.__version__
-   1.3
-   
-Try some of the examples in the examples/ directory shipped with the
-distribution or have a look at some of the :doc:`Examples <examples>`
-in this documentation.
-
-Have fun :)

docs/source/start/downloading.rst

+Downloading
+===========
+
+Latest Stable Release
+---------------------
+
+The latest stable releases can be downloaded from the
+`Downloads <http://bitbucket.org/prologic/circuits/downloads/>`_ page.
+
+Latest Development Source Code
+------------------------------
+
+We use `Mercurial <http://mercurial.selenic.com/>`_ for source control
+and code sharing.
+
+The latest development branch can be cloned using the following command:
+
+.. code-block:: sh
+   
+   $ hg clone http://bitbucket.org/prologic/circuits/
+   
+For further instructions on how to use Mercurial, please refer to the
+`Mercurial Book <http://mercurial.selenic.com/wiki/MercurialBook>`_.

docs/source/start/index.rst

+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   quick
+   downloading
+   installing
+   requirements

docs/source/start/installing.rst

+Installing
+==========
+
+If you have not installed circuits via the the
+`setuptools <http://pypi.python.org/pypi/setuptools>`_ easy_install tool,
+then the following installation instructions will apply to you. Either
+you've downloaded a source package or cloned the development repository.
+
+Installing from a Source Package
+--------------------------------
+
+.. code-block:: sh
+
+   $ python setup.py install
+
+For other installation options see:
+
+.. code-block:: sh
+
+   $ python setup.py --help install
+
+Installing from the Development Repository
+------------------------------------------
+
+If you have cloned the development repository, it is recommended that you
+use setuptools and use the following command:
+
+.. code-block:: sh
+
+   $ python setup.py build develop
+
+**NB:** The "build" command is required when installing from the development
+repository (*build creates the version file which is built dynamically*).
+
+This will allow you to regularly update your copy of the circuits development
+repository by simply performing the following in the circuits working directory:
+
+.. code-block:: sh
+
+   $ hg pull -u
+
+**NB**: You do not need to reinstall if you have installed with setuptools via
+the circuits repository and used setuptools to install in "develop" mode.

docs/source/start/quick.rst

+Quick Start Guide
+=================
+
+The easiest way to download and install circuits is to use the
+`setuptools <http://pypi.python.org/pypi/setuptools>`_ easy_install tool:
+
+.. code-block:: sh
+   
+   $ easy_install circuits
+   
+
+Now that you have successfully downloaded and installed circuits, let's
+test that circuits is properly installed and working.
+
+First, let's check the installed version:
+
+.. code-block:: python
+   
+   >>> import circuits
+   >>> print circuits.__version__
+   1.3
+   
+Try some of the examples in the examples/ directory shipped with the
+distribution or check out some :doc:`Applications using circuits <../users>`
+
+Have fun :)

docs/source/start/requirements.rst

+.. _Python Standard Library: http://docs.python.org/library/
+
+Requirements and Dependencies
+=============================
+
+circuits has no **requird** dependencies beyond the `Python Standard Library`_.
+(*with the exception of Python 2.5 installations*).
+
+Python 2.5
+----------
+
+- `processing <http://pypi.python.org/pypi/processing/>`_
+  -- For multi-processing support.
+
+- `simplejson <http://pypi.python.org/pypi/simplejson/>`_
+  -- For JSON support in circuits.web dispatchers and controllers.
+
+Other Optional Dependencies
+---------------------------
+
+These depdencies are not strictly requiree and only add additional
+features such as the option for a routes dispatcher for circuits.web
+and rendering of component graphs for your application.
+
+- `Routes <http://pypi.python.org/pypi/Routes/>`_
+  -- For routes based dispatching in circuits.web
+
+- `pydot <http://pypi.python.org/pypi/pydot/>`_
+  -- For rendering component graphs of an application.

docs/source/todo.rst

+Documentation TODO
+==================
+
+.. todolist::

docs/source/users.rst

+Users of circuits
+=================
+
+Applications written in circuits
+--------------------------------
+
+Applications integrating circuits
+---------------------------------
+
+Other Users
+-----------
+

docs/source/web.rst

-Web Framework
-=============
-
-.. toctree::
-   :maxdepth: 1
-
-   web/introduction
-   web/gettingstarted
-   web/basics
-   web/howtos
-   web/deployment
-   web/controllers
-   web/dispatchers
-   web/tools

docs/source/web/index.rst

+==========================
+The circuits.web Framework
+==========================
+
+.. toctree::
+   :maxdepth: 1
+
+   introduction
+   gettingstarted
+   basics
+   howtos
+   deployment
+   controllers
+   dispatchers
+   tools