1 files changed, 147 insertions, 0 deletions
diff --git a/docs/python-api.rst b/docs/python-api.rst
new file mode 100644
index 0000000..a22ed2a
--- /dev/null
+++ b/docs/python-api.rst
@@ -0,0 +1,147 @@
+Python API
+==========
+
+Compiling files
+---------------
+
+Very basic usage is simple enough::
+
+    from scss import Scss
+    css = Scss()
+    css.compile("a { color: red + green; }")
+
+
+Configuration
+-------------
+
+There are several configuration variables in the ``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
+probably not what you want.
+
+``LOAD_PATHS``: An iterable of paths to search when using``@import``.
+
+``STATIC_ROOT``: Used for finding sprite files.  Defaults to
+``$PROJECT_ROOT/static``.
+
+``ASSETS_ROOT``: Generated sprites are saved here.  Defaults to
+``$STATIC_ROOT/assets``.
+
+``CACHE_ROOT``: Used for storing cached sprite information.  Defaults to
+``ASSETS_ROOT``.
+
+``STATIC_URL``: URL equivalent to ``STATIC_ROOT``.  Defaults to ``static/``.
+
+``ASSETS_URL``: URL equivalent to ``ASSETS_ROOT``.  Defaults to ``static/assets/``.
+
+``SPRTE_MAP_DIRECTION``: Direction in which to arrange sprites in a
+spritesheet.  Defaults to ``vertical``; may be changed to ``horizontal``,
+``diagonal``, or ``smart``.
+
+``VERBOSITY``: Increase spew from the compiler.  Defaults to ``1``.
+
+``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::
+
+    import os
+    import fnmatch
+    
+    import scss
+    
+    from django.conf import settings
+    from django.utils.datastructures import SortedDict
+    from django.contrib.staticfiles import finders
+    
+    
+    def finder(glob):
+        """
+        Finds all files in the django finders for a given glob,
+        returns the file path, if available, and the django storage object.
+        storage objects must implement the File storage API:
+        https://docs.djangoproject.com/en/dev/ref/files/storage/
+        """
+        for finder in finders.get_finders():
+            for path, storage in finder.list([]):
+                if fnmatch.fnmatchcase(path, glob):
+                    yield path, storage
+    
+    
+    # STATIC_ROOT is where pyScss looks for images and static data.
+    # STATIC_ROOT can be either a fully qualified path name or a "finder"
+    # iterable function that receives a filename or glob and returns a tuple
+    # of the file found and its file storage object for each matching file.
+    # (https://docs.djangoproject.com/en/dev/ref/files/storage/)
+    scss.config.STATIC_ROOT = finder
+    scss.config.STATIC_URL = settings.STATIC_URL
+    
+    # ASSETS_ROOT is where the pyScss outputs the generated files such as spritemaps
+    # and compile cache:
+    scss.config.ASSETS_ROOT = os.path.join(settings.MEDIA_ROOT, 'assets/')
+    scss.config.ASSETS_URL = settings.MEDIA_URL + 'assets/'
+    
+    # These are the paths pyScss will look ".scss" files on. This can be the path to
+    # the compass framework or blueprint or compass-recepies, etc.
+    scss.config.LOAD_PATHS = [
+        '/usr/local/www/sass/frameworks/',
+        '/Library/Ruby/Gems/1.8/gems/compass-0.11.5/frameworks/compass/stylesheets/',
+        '/Library/Ruby/Gems/1.8/gems/compass-0.11.5/frameworks/blueprint/stylesheets/',
+    ]
+    
+    # This creates the Scss object used to compile SCSS code. In this example,
+    # _scss_vars will hold the context variables:
+    _scss_vars = {}
+    _scss = scss.Scss(
+        scss_vars=_scss_vars,
+        scss_opts={
+            'compress': True,
+            'debug_info': True,
+        }
+    )
+    
+    # 1. Compile from a string:
+    compiled_css_from_string = _scss.compile('@import "file2"; a {color: red + green; }')
+    
+    # 2. Compile from a file:
+    compiled_css_from_file = _scss.compile(scss_file='file1.scss')
+    
+    # 3. Compile from a set of files (use SortedDict or collections.OrderedDict to
+    # maintain the compile order):
+    _scss._scss_files = SortedDict((
+        ('file2.scss', open('file2.scss').read()),
+        ('file3.scss', open('file3.scss').read()),
+        ('file4.scss', open('file4.scss').read()),
+    ))
+    compiled_css_from_files = _scss.compile()
+
+.. note::
+
+    The API here is likely to be improved in 1.3, to avoid the need for calling
+    underscored functions.
+
+
+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.
+
+.. todo::
+
+    Document the extension API once it's final.