Document some of the shiny new API.

4 files changed, 128 insertions, 29 deletions

diff --git a/docs/back-matter.rst b/docs/back-matter.rst
index 5245d41..9df246b 100644
--- a/docs/back-matter.rst
+++ b/docs/back-matter.rst
@@ -67,8 +67,8 @@ working hours.  Yelp does not claim copyright.
 Changelog
 ---------
 
-1.3.0 (unreleased)
-^^^^^^^^^^^^^^^^^^
+1.3.0 (Oct 15, 2014)
+^^^^^^^^^^^^^^^^^^^^
 
 This is a somewhat transitional release along the road to 2.0, which will
 remove a lot of deprecated features.
diff --git a/docs/conf.py b/docs/conf.py
index f4d5642..ab654f9 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -27,6 +27,8 @@ import sys, os
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode']
 
+autodoc_member_order = 'bysource'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
diff --git a/docs/python-api.rst b/docs/python-api.rst
index a22ed2a..ef047f4 100644
--- a/docs/python-api.rst
+++ b/docs/python-api.rst
@@ -1,8 +1,19 @@
 Python API
 ==========
 
+Legacy API
+----------
+
+.. warning::
+
+    This API is still supported while the new API below is worked out, but it's
+    slated for deprecation and eventual removal.  If you don't need any of the
+    features not yet available with the new API, consider porting as soon as
+    possible.
+
+
 Compiling files
----------------
+***************
 
 Very basic usage is simple enough::
 
@@ -12,10 +23,10 @@ Very basic usage is simple enough::
 
 
 Configuration
--------------
+*************
 
-There are several configuration variables in the ``scss.config`` module that
-you may wish to change.
+There are several configuration variables in the :py:mod:`scss.config` module
+that you may wish to change.
 
 ``PROJECT_ROOT``: Root of your entire project.  Used only to construct defaults
 for other variables.  Defaults to the root of the pyScss installation, which is
@@ -44,19 +55,9 @@ spritesheet.  Defaults to ``vertical``; may be changed to ``horizontal``,
 
 ``DEBUG``: Set to true to make parse errors fatal.  Defaults to false.
 
-.. warning::
-
-    Configuration via monkeypatching is fraught with issues.  If you don't need
-    the Compass sprite functionality, stick with passing ``search_paths`` to
-    the ``Scss`` constructor, and don't touch these variables at all.
-
-    The current plan is to introduce a new mechanism for Compass configuration
-    in 1.3 with deprecation warnings, and remove ``scss.config`` entirely in
-    2.0.
-
 
 Django example
---------------
+**************
 
 A rough example of using pyScss with Django::
 
@@ -136,12 +137,105 @@ A rough example of using pyScss with Django::
     underscored functions.
 
 
+New API
+-------
+
+The simplest example::
+
+    from scss.compiler import compile_string
+
+    print(compile_string("a { color: red + green; }"))
+
+:py:func:`scss.compiler.compile_string` is just a simple wrapper around the
+:py:class:`scss.compiler.Compiler` class::
+
+    from scss.compiler import Compiler
+
+    compiler = Compiler()
+    print(compiler.compile_string("a { color: red + green; }"))
+
+The most common arguments passed to `Compiler` are:
+
+**search_path**
+    A list of paths to search for ``@import``\ s.  May be either strings or
+    :py:class:`pathlib.Path` objects.
+
+
 Extending pyScss
 ----------------
 
-There is some support for adding custom functions from Python, but the API is
-explicitly undocumented and subject to change.  Watch this space.
+A significant advantage to using pyScss is that you can inject Python values
+and code into the Sass compilation process.
+
+Injecting values
+****************
+
+You can define Sass values by creating and populating a :class:`scss.namespace.Namespace`::
+
+    from scss.namespace import Namespace
+    from scss.types import String
+
+    namespace = Namespace()
+    namespace.set_variable('$base-url', String('http://localhost/'))
+    compiler = Compiler(namespace=namespace)
+    compiler.compile_string('div { background: url($base-url); }')
+
+Now, ``$base-url`` will be available to the compiled Sass code, just like any
+other variable.  Note that the value given must be one of the Sass types
+defined in :py:mod:`scss.types`.
+
+Injecting functions
+*******************
+
+You can inject functions the same way::
+
+    def square(x):
+        return x * x
+
+    namespace.set_function('square', 1, square)
+
+This creates a function ``square`` for use in your Sass source.  Optional
+arguments, keyword arguments, and slurpy arguments are all supported
+automatically.  The arguments are Sass types, and the return value must be one
+as well.
+
+The second argument is the arity — the number of required arguments, or None if
+any number of arguments is allowed.  Sass functions can be overloaded by arity,
+so this is required.  For functions with optional arguments, adding the same
+function multiple times can be tedious and error-prone, so the ``declare``
+decorator is also available::
+
+    @namespace.declare
+    def square(x):
+        return x * x
+
+This will inspect the arguments for you and register the function with all
+arities it accepts.  The function name is determined from the Python name:
+underscores become hyphens, and trailing underscores are removed.  If you'd
+prefer to be more explicit, there's also a ``declare_alias``::
+
+    @namespace.declare_alias('square')
+    def square(x):
+        return x * x
+
+
+API reference
+-------------
+
+scss.compiler
+*************
+
+.. automodule:: scss.compiler
+    :members:
+
+scss.namespace
+**************
+
+.. automodule:: scss.namespace
+    :members:
 
-.. todo::
+scss.extension
+**************
 
-    Document the extension API once it's final.
+.. automodule:: scss.extension
+    :members:
diff --git a/docs/usage.rst b/docs/usage.rst
index 235c030..65b5379 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -9,8 +9,11 @@ known to work.  Install with pip::
 
     pip install pyScss
 
-Its lone Python dependency is the ``six`` library, which pip should install for
-you.
+It has a handful of pure-Python dependencies, which pip should install for you:
+
+* ``six``
+* ``enum34`` (for Python 3.3 and below)
+* ``pathlib`` (for Python 3.3 and below)
 
 There's also an optional C speedup module, which requires having ``libpcre``
 and its development headers installed, with UTF-8 support enabled (which it is
@@ -22,17 +25,17 @@ Usage
 
 Run from the command line by using ``-m``::
 
-    python -mscss < file.scss
+    python -m scss < file.scss
 
 Specify directories to search for imports with ``-I``.  See ``python -mscss
 --help`` for more options.
 
 .. note::
 
-    ``-mscss`` will only work in Python 2.7 and above.  For Python 2.5 and 2.6,
-    ``-m`` doesn't work with packages, and you need to invoke::
+    ``-mscss`` will only work in Python 2.7 and above.  In Python 2.6, ``-m``
+    doesn't work with packages, and you need to invoke this instead::
 
-        python -mscss.tool
+        python -m scss.tool
 
 
 
@@ -66,8 +69,8 @@ Example session::
 Compass example
 ---------------
 
-With ``--load-path`` or ``scss.config.LOAD_PATHS`` set to Compass and Blueprint
-roots, you can compile with Compass like with the following::
+With ``--load-path`` set to Compass and Blueprint roots, you can compile with
+Compass like with the following::
 
     @option compress: no;