Updates boo's documentation to the new Sphinx format.

docs/Makefile

@@ -37,6 +37,8 @@ clean:
 	-rm -rf $(BUILDDIR)/*
 
 html:
+	stylus -o ~/work/caffeine-theme/caffeine/static ~/work/caffeine-theme/caffeine/stylus/screen.styl
+	mv ~/work/caffeine-theme/caffeine/static/screen.css ~/work/caffeine-theme/caffeine/static/screen.css_t
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

docs/source/api/base.rst

@@ -0,0 +1,64 @@
+{} Base
+*******
+
+.. class:: Base
+   :module: boo
+
+   .. code-block:: haskell
+
+      Base :: { init! :: @this:Object*, Any... -> this }
+
+   The root object for basing all the OOP code. Provides all of *Boo's*
+   primitive combinators in an easy and extensible OOP-way.
+
+
+
+Creating instances
+==================
+
+.. function:: Base.make()
+   :noindex:
+
+   .. code-block:: haskell
+
+      make :: @this:Object, Any... -> Object <| this
+
+   Constructs new instances of the object the function is being applied to.
+
+   .. rst-class:: detail-link
+
+      :doc:`+ <base/make>`
+
+
+.. function:: Base.derive(sources...)
+   :noindex:
+
+   .. code-block:: haskell
+
+      derive :: @this:Object, (Object | DataObject)... -> Object <| this
+
+   Constructs a new object that inherits from the object this function is
+   being applied to, and extends it with the provided *mixins*.
+
+   .. rst-class:: detail-link
+
+      :doc:`+ <base/derive>`
+
+
+
+Summary
+=======
+
+.. code-block:: haskell
+
+   init!  :: @this:Object*, Any... -> this
+   make   :: @this:Object, Any... -> Object <| this
+   derive :: @this:Object, Any... -> Object <| this
+
+
+.. -------------------------------------------------------------------------
+.. toctree::
+   :hidden:
+
+   base/make
+   base/derive

docs/source/api/base/derive.rst

@@ -0,0 +1,36 @@
+λ derive()
+**********
+
+.. function:: Base.derive(sources...)
+   :module: boo
+
+   .. code-block:: haskell
+
+      derive :: @this:Object, (Object | DataObject)... -> Object <| this
+
+   Constructs a new object that inherits from the object this function is
+   being applied to, and extends it with the provided *mixins*.
+
+
+Derive provides a thin abstraction layer upon the primitive :func:`derive`,
+with the only difference being that instead of taking a *[[Prototype]]* as the first
+parameter, it uses the object the ``derive`` function has been applied to for
+that.
+
+.. code-block:: javascript
+
+   var Point2d = { x: 0, y: 0 }
+   var Point3d = boo.derive(Point2d, { z: 1 })
+
+
+   // Does mostly the same thing as:
+   var Point2d = Base.derive({ x: 0, y: 0 })
+   var Point3d = Point2d.derive({ z: 1 })
+
+
+Related functionality
+=====================
+
+:doc:`λ derive <../derive>`
+   The ``derive`` primitive function documentation page describes the
+   function's semantics in more details.

docs/source/api/base/make.rst

@@ -0,0 +1,62 @@
+λ make()
+********
+
+.. function:: Base.make()
+   :module: boo
+
+   .. code-block:: haskell
+
+      make :: @this:Object, Any... -> Object <| this
+
+   Constructs new instances of the object the function is being applied to.
+
+
+This is a generic method that will clone the current object and initialise it
+with an initialisation method (``init``). Such initialisation method is taken
+from the object the ``make`` method is applied to. This approach makes this
+method rather flexible:
+
+.. code-block:: javascript
+
+   var fruit = { init: function(name){ this.name  = name
+                                       this.bites = 0 }
+               , eat:  function(){ return this.bites++?    'Already eaten.'
+                                   :      /* otherwise */  this.name + ' is being eaten.' }}
+
+   // This creates a new object with `fruit' as its prototype, and
+   // invokes `fruit's `init' method on it.
+   var apple = Base.make.call(fruit, 'Apple')
+
+   apple.eat()
+   // => 'Apple has been eaten.'
+   apple.eat()
+   // => 'Already eaten.'
+
+   // This creates a new object with `apple' as its prototype, and
+   // invokes `apple's `init' method on it. Since apple itself doesn't
+   // define an `init' method, it's taken from `fruit'.
+   var pie = Base.make.call(apple, 'Apple pie')
+   pie.eat()
+   // => 'Apple pie has been eaten.'
+
+   
+The generic object on which ``make`` will be called should either not implement
+an ``init`` method at all, or match the following interface:
+
+.. code-block:: haskell
+
+   type Initialisable :: { init! :: @this:Object*, Any... -> this }
+
+
+
+Limitations
+===========
+
+While *JavaScript's* own ``new`` operator allows one to write factory functions
+that work seamlessly with ``new-ful`` invocations, the ``make`` method won't
+change the instance depending on what ``init`` returns. That is, it doesn't use
+``init`` as a *transformer* function, but rather as an impure initialisation
+routine.
+
+If you want to write a factory function, you'll need to use :func:`Base.derive` and
+invoke the right initialisation routine instead.

docs/source/api/boo.rst

@@ -0,0 +1,194 @@
+{} boo
+******
+
+
+.. module:: boo
+   :synopsis: Prototypical utilities for Object Orientation / Composition
+   :platform: ECMAScript 5
+
+
+The **boo** module provides primitives that abstract the semantics of
+prototypical object orientation, as implemented by *JavaScript*, such
+that these features can be explored with a more usable interface.
+
+The module provides such features as the stand-alone functions:
+:func:`extend` and :func:`derive`, as well as an Object interface that can be
+extended upon: :class:`Base`.
+
+
+
+Internal
+========
+
+Interfaces
+----------
+
+.. data:: DataObject
+
+   .. code-block:: haskell
+
+      type DataObject :: { "to_data" :: () -> Object }
+
+
+.. data:: Mixin
+
+   .. code-block:: haskell
+
+      type Mixin :: Object | DataObject
+
+
+
+Helpers
+-------
+
+.. function:: copy_property(source, target, property)
+
+   .. code-block:: haskell
+
+      copy_property! :: Object, target:Object*, String -> target
+
+   Copies a property from ``source`` to ``target``.
+
+
+
+.. function:: data_obj_p(subject)
+
+   .. code-block:: haskell
+
+      data_obj? :: Any -> Bool
+
+   Checks if the given subject matches the :obj:`DataObject` interface.
+
+
+
+.. function:: resolve_mixin(object)
+
+   .. code-block:: haskell
+
+      resolve_mixin :: Object -> Object
+
+   Returns the proper mixin for the given ``object``.
+
+
+
+.. function:: fast_extend(object, mixins)
+
+   .. code-block:: haskell
+
+      fast_extend! :: target:Object*, [Mixin] -> target
+
+   Extends the target object with the provided mixins, using a
+   right-most precedence rule — when there's a property conflict, the
+   property defined in the last object wins.
+
+   :obj:`DataObject` instances are properly handled by the
+   :func:`resolve_mixin` function.
+
+
+
+Public
+======
+
+Basic primitives
+----------------
+
+.. function:: extend(target, mixins...)
+   :noindex:
+
+   .. code-block:: haskell
+
+      extend!:: Object*, Mixin... -> Object
+
+   Extends the target object with the provided ``mixins``, using a
+   right-most precedence rule.
+
+   .. rst-class:: detail-link
+
+      :doc:`+ <extend>`
+
+
+.. function:: merge(mixins...)
+   :noindex:
+
+   .. code-block:: haskell
+
+      merge :: Mixin... -> Object
+
+   Creates a new object that merges the provided ``mixins``, using a
+   right-most precedence rule.
+
+   .. rst-class:: detail-link
+
+      :doc:`+ <merge>`
+
+
+.. function:: derive(prototype, mixins...)
+   :noindex:
+
+   .. code-block:: haskell
+
+      derive :: Object, Mixin... -> Object
+
+   Creates a new object inheriting from the given ``prototype`` and
+   extends the new instance with the provided ``mixins``.
+
+   .. rst-class:: detail-link
+
+      :doc:`+ <derive>`
+
+
+
+Root object
+-----------
+
+.. class:: Base
+   :noindex:
+
+   .. code-block:: haskell
+
+      object Base :: { init!  :: @this:Object*, Any... -> this
+                       make   :: @this:Object, Any... -> Object <| this
+                       derive :: @this:Object, Any... -> Object <| this
+                     }
+
+   The root object for basing all the OOP code. Provides all of
+   *Boo's* primitive combinators in an easy and extensible OOP-way.
+
+   .. rst-class:: detail-link
+
+      :doc:`+ <base>`
+
+
+
+Summary
+=======
+
+.. code-block:: haskell
+
+   -- Interface
+      type DataObject :: { "to_data" :: () -> Object }
+      type Mixin      :: Object | DataObject
+
+   -- Internal
+      copy_property! :: Object, target:Object*, String -> target
+      data_obj?      :: Any -> Bool
+      resolve_mixin  :: Object -> Object
+      fast_extend!   :: target:Object*, [Mixin] -> target
+
+   -- Public
+      extend!     :: Object*, Mixin... -> Object
+      merge       :: Mixin... -> Object
+      derive      :: Object, Mixin... -> Object
+      object Base :: { init!  :: @this:Object*, Any... -> this
+                       make   :: @this:Object, Any... -> Object <| this
+                       derive :: @this:Object, Any... -> Object <| this
+                     }
+
+
+.. toctree::
+   :hidden:
+
+   extend
+   merge
+   derive
+   base