Merge remote-tracking branch 'cweb/master'

37 files changed, 3738 insertions, 0 deletions

diff --git a/docs/source/_static/goblin.png b/docs/source/_static/goblin.png
new file mode 100644
index 00000000..e20265e6
--- /dev/null
+++ b/docs/source/_static/goblin.png
diff --git a/docs/source/_static/placeholder b/docs/source/_static/placeholder
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/docs/source/_static/placeholder
diff --git a/docs/source/_static/snugglygoblin.png b/docs/source/_static/snugglygoblin.png
new file mode 100644
index 00000000..f325ae4b
--- /dev/null
+++ b/docs/source/_static/snugglygoblin.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 00000000..0b2bccac
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,247 @@
+# -*- coding: utf-8 -*-
+#
+# GNU MediaGoblin documentation build configuration file, created by
+# sphinx-quickstart on Thu Apr  7 20:10:27 2011.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# 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.intersphinx']
+intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None)}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['source/_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'GNU MediaGoblin'
+copyright = u'2011, 2012 GNU MediaGoblin contributors'
+
+# 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.
+#
+try:
+    from mediagoblin._version import __version__
+    # The short X.Y version.
+    version = '.'.join(__version__.split('.')[0:2])
+    # The full version, including alpha/beta/rc tags.
+    release = __version__
+except ImportError:
+    version = 'unknown'
+    release = 'unknown'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build', 'mgext', '_templates', '_static']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+# html_theme = 'default'
+html_theme = 'mg'
+
+# 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
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = ['themes']
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = 'logo_docs.png'
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'GNUMediaGoblindoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'GNUMediaGoblin.tex', u'GNU MediaGoblin Documentation',
+   u'Chris Webber, et al', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation',
+     [u'Chris Webber, et al'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', u'gnumediagoblin',
+   'GNU MediaGoblin', 'Media sharing web application.', 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst
new file mode 100644
index 00000000..122a3297
--- /dev/null
+++ b/docs/source/devel/codebase.rst
@@ -0,0 +1,183 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+.. _codebase-chapter:
+
+========================
+ Codebase Documentation
+========================
+
+.. contents:: Sections
+   :local:
+
+
+This chapter covers the libraries that GNU MediaGoblin uses as well as
+various recipes for getting things done.
+
+.. Note::
+
+   This chapter is in flux.  Clearly there are things here that aren't
+   documented.  If there's something you have questions about, please
+   ask!
+
+   See `the join page on the website <http://mediagoblin.org/join/>`_
+   for where we hang out.
+
+For more information on how to get started hacking on GNU MediaGoblin,
+see `the wiki <http://wiki.mediagoblin.org/>`_, and specifically, go
+through the
+`Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_
+which explains generally how to get going with running an instance for
+development.
+
+
+What's where
+============
+
+After you've run checked out mediagoblin and followed the virtualenv
+instantiation instructions, you're faced with the following directory
+tree::
+
+    mediagoblin/
+    |- mediagoblin/              # source code
+    |  |- db/                    # database setup
+    |  |- tools/                 # various utilities
+    |  |- init/                  # "initialization" tools (arguably should be in tools/)
+    |  |- tests/                 # unit tests
+    |  |- templates/             # templates for this application
+    |  |- media_types/           # code for processing, displaying different media
+    |  |- storage/               # different storage backends
+    |  |- gmg_commands/          # command line tools (./bin/gmg)
+    |  |- themes/                # pre-bundled themes
+    |  |
+    |  |  # ... some submodules here as well for different sections
+    |  |  # of the application... here's just a few
+    |  |- auth/                  # authentication (login/registration) code
+    |  |- user_dev/              # user pages (under /u/), including media pages
+    |  \- submit/                # submitting media for processing
+    |
+    |- docs/                     # documentation
+    |- devtools/                 # some scripts for developer convenience
+    |
+    |- user_dev/                 # local instance sessions, media, etc
+    |
+    |  # the below directories are installed into your virtualenv checkout
+    |
+    |- bin/                      # scripts
+    |- develop-eggs/
+    |- lib/                      # python libraries installed into your virtualenv
+    |- include/
+    |- mediagoblin.egg-info/
+    \- parts/
+
+
+As you can see, all the code for GNU MediaGoblin is in the
+``mediagoblin`` directory.
+
+Here are some interesting files and what they do:
+
+:routing.py: maps url paths to views
+:views.py:   views handle http requests
+:forms.py:   wtforms stuff for this submodule
+
+You'll notice that there are several sub-directories: tests,
+templates, auth, submit, ...
+
+``tests`` holds the unit test code.
+
+``templates`` holds all the templates for the output.
+
+``auth`` and ``submit`` are modules that enacpsulate authentication
+and media item submission.  If you look in these directories, you'll
+see they have their own ``routing.py``, ``view.py``, and forms.py in
+addition to some other code.
+
+You'll also notice that mediagoblin/db/ contains quite a few things,
+including the following:
+
+:models.py:      This is where the database is set up
+:mixin.py:       Certain functions appended to models from here
+:migrations.py:  When creating a new migration (a change to the
+                 database structure), we put it here
+
+
+Software Stack
+==============
+
+* Project infrastructure
+
+  * `Python <http://python.org/>`_: the language we're using to write
+    this
+
+  * `Py.Test <http://pytest.org/>`_:
+    for unit tests
+
+  * `virtualenv <http://www.virtualenv.org/>`_: for setting up an
+    isolated environment to keep mediagoblin and related packages
+    (potentially not required if MediaGoblin is packaged for your
+    distro)
+
+* Data storage
+
+  * `SQLAlchemy <http://sqlalchemy.org/>`_: SQL ORM and database
+    interaction library for Python. Currently we support sqlite and
+    postgress as backends.
+
+* Web application
+
+  * `Paste Deploy <http://pythonpaste.org/deploy/>`_ and
+    `Paste Script <http://pythonpaste.org/script/>`_: we'll use this for
+    configuring and launching the application
+
+  * `werkzeug <http://werkzeug.pocoo.org/>`_: nice abstraction layer
+    from HTTP requests, responses and WSGI bits
+
+  * `itsdangerous <http://pythonhosted.org/itsdangerous/>`_:
+    for handling sessions
+
+  * `Jinja2 <http://jinja.pocoo.org/docs/>`_: the templating engine
+
+  * `WTForms <http://wtforms.simplecodes.com/>`_: for handling,
+    validation, and abstraction from HTML forms
+
+  * `Celery <http://celeryproject.org/>`_: for task queuing (resizing
+    images, encoding video, ...)
+
+  * `Babel <http://babel.edgewall.org>`_: Used to extract and compile
+    translations.
+
+  * `Markdown (for python) <http://pypi.python.org/pypi/Markdown>`_:
+    implementation of `Markdown <http://daringfireball.net/projects/markdown/>`_
+    text-to-html tool to make it easy for people to write richtext
+    comments, descriptions, and etc.
+
+  * `lxml <http://lxml.de/>`_: nice xml and html processing for
+    python.
+
+* Media processing libraries
+
+  * `Python Imaging Library <http://www.pythonware.com/products/pil/>`_:
+    used to resize and otherwise convert images for display.
+
+  * `GStreamer <http://gstreamer.freedesktop.org/>`_: (Optional, for
+    video hosting sites only) Used to transcode video, and in the
+    future, probably audio too.
+
+  * `chardet <http://pypi.python.org/pypi/chardet>`_: (Optional, for
+    ascii art hosting sites only)  Used to make ascii art thumbnails.
+
+* Front end
+
+  * `JQuery <http://jquery.com/>`_: for groovy JavaScript things
+
+
diff --git a/docs/source/devel/originaldesigndecisions.rst b/docs/source/devel/originaldesigndecisions.rst
new file mode 100644
index 00000000..2843870c
--- /dev/null
+++ b/docs/source/devel/originaldesigndecisions.rst
@@ -0,0 +1,336 @@
+.. _original-design-decisions-chapter:
+
+===========================
+ Original Design Decisions
+===========================
+
+.. contents:: Sections
+   :local:
+
+
+This chapter talks a bit about design decisions.
+
+Note: This is an outdated document.  It's more or less the historical
+reasons for a lot of things.  That doesn't mean these decisions have
+stayed the same or we haven't changed our minds on some things!
+
+
+Why GNU MediaGoblin?
+====================
+
+Chris and Will on "Why GNU MediaGoblin":
+
+    Chris came up with the name MediaGoblin.  The name is pretty fun.
+    It merges the idea that this is a Media hosting project with
+    Goblin which sort of sounds like gobbling.  Here's a piece of
+    software that gobbles up your media for all to see.
+
+    `According to Wikipedia <http://en.wikipedia.org/wiki/Goblin>`_, a
+    goblin is:
+
+        a legendary evil or mischievous illiterate creature, described
+        as grotesquely evil or evil-like phantom
+
+    So are we evil?  No.  Are we mischievous or illiterate?  Not
+    really.  So what kind of goblin are we thinking about?  We're
+    thinking about these goblins:
+
+    .. figure:: ../_static/goblin.png
+       :alt: Cute goblin with a beret.
+
+       *Figure 1: Cute goblin with a beret.  llustrated by Chris
+       Webber*
+
+    .. figure:: ../_static/snugglygoblin.png
+       :scale: 50%
+       :alt: Snuggly goblin with a beret.
+
+       *Figure 2: Snuggly goblin.  Illustrated by Karen Rustad*
+
+    Those are pretty cute goblins.  Those are the kinds of goblins
+    we're thinking about.
+
+    Chris started doing work on the project after thinking about it
+    for a year.  Then, after talking with Matt and Rob, it became an
+    official GNU project.  Thus we now call it GNU MediaGoblin.
+
+    That's a lot of letters, though, so in the interest of brevity and
+    facilitating easier casual conversation and balancing that with
+    what's important to us, we have the following rules:
+
+    1. "GNU MediaGoblin" is the name we're going to use in all official
+       capacities: web site, documentation, press releases, ...
+
+    2. In casual conversation, it's ok to use more casual names.
+
+    3. If you're writing about the project, we ask that you call it GNU 
+       MediaGoblin.
+
+    4. If you don't like the name, we kindly ask you to take a deep
+       breath, think a happy thought about cute little goblins playing
+       on a playground and taking cute pictures of themselves, and let
+       it go.  (Will added this one.)
+
+
+Why Python
+==========
+
+Chris Webber on "Why Python":
+
+    Because I know Python, love Python, am capable of actually making
+    this thing happen in Python (I've worked on a lot of large free
+    software web applications before in Python, including `Miro
+    Community`_, the `Miro Guide`_, a large portion of `Creative
+    Commons`_, and a whole bunch of things while working at `Imaginary
+    Landscape`_).  Me starting a project like this makes sense if it's
+    done in Python.
+
+    You might say that PHP is way more deployable, that Rails has way
+    more cool developers riding around on fixie bikes---and all of
+    those things are true.  But I know Python, like Python, and think
+    that Python is pretty great.  I do think that deployment in Python
+    is not as good as with PHP, but I think the days of shared hosting
+    are (thankfully) coming to an end, and will probably be replaced
+    by cheap virtual machines spun up on the fly for people who want
+    that sort of stuff, and Python will be a huge part of that future,
+    maybe even more than PHP will.  The deployment tools are getting
+    better.  Maybe we can use something like Silver Lining.  Maybe we
+    can just distribute as ``.debs`` or ``.rpms``.  We'll figure it
+    out when we get there.
+
+    Regardless, if I'm starting this project, which I am, it's gonna
+    be in Python.
+
+.. _Miro Community: http://mirocommunity.org/
+.. _Miro Guide: http://miroguide.org/
+.. _Creative Commons: http://creativecommons.org/
+.. _Imaginary Landscape: http://www.imagescape.com/
+
+
+Why WSGI Minimalism
+===================
+
+Chris Webber on "Why WSGI Minimalism":
+
+    If you notice in the technology list I list a lot of components
+    that are very "django-like", but not actually `Django`_
+    components.  What can I say, I really like a lot of the ideas in
+    Django!  Which leads to the question: why not just use Django?
+
+    While I really like Django's ideas and a lot of its components, I
+    also feel that most of the best ideas in Django I want have been
+    implemented as good or even better outside of Django.  I could
+    just use Django and replace the templating system with Jinja2, and
+    the form system with wtforms, and the database with MongoDB and
+    MongoKit, but at that point, how much of Django is really left?
+
+    I also am sometimes saddened and irritated by how coupled all of
+    Django's components are.  Loosely coupled yes, but still coupled.
+    WSGI has done a good job of providing a base layer for running
+    applications on and if you know how to do it yourself [1]_, it's
+    not hard or many lines of code at all to bind them together
+    without any framework at all (not even say `Pylons`_, `Pyramid`_
+    or `Flask`_ which I think are still great projects, especially for
+    people who want this sort of thing but have no idea how to get
+    started).  And even at this already really early stage of writing
+    MediaGoblin, that glue work is mostly done.
+
+    Not to say I don't think Django isn't great for a lot of things.
+    For a lot of stuff, it's still the best, but not for MediaGoblin,
+    I think.
+
+    One thing that Django does super well though is documentation.  It
+    still has some faults, but even with those considered I can hardly
+    think of any other project in Python that has as nice of
+    documentation as Django.  It may be worth learning some lessons on
+    documentation from Django [2]_, on that note.
+
+    I'd really like to have a good, thorough hacking-howto and
+    deployment-howto, especially in the former making some notes on
+    how to make it easier for Django hackers to get started.
+
+.. _Django: http://www.djangoproject.com/
+.. _Pylons: http://pylonshq.com/
+.. _Pyramid: http://docs.pylonsproject.org/projects/pyramid/dev/
+.. _Flask: http://flask.pocoo.org/
+
+.. [1] http://pythonpaste.org/webob/do-it-yourself.html
+.. [2] http://pycon.blip.tv/file/4881071/
+
+
+Why MongoDB
+===========
+
+(Note: We don't use MongoDB anymore.  This is the original rationale,
+however.)
+
+Chris Webber on "Why MongoDB":
+
+    In case you were wondering, I am not a NOSQL fanboy, I do not go
+    around telling people that MongoDB is web scale.  Actually my
+    choice for MongoDB isn't scalability, though scaling up really
+    nicely is a pretty good feature and sets us up well in case large
+    volume sites eventually do use MediaGoblin.  But there's another
+    side of scalability, and that's scaling down, which is important
+    for federation, maybe even more important than scaling up in an
+    ideal universe where everyone ran servers out of their own
+    housing.  As a memory-mapped database, MongoDB is pretty hungry,
+    so actually I spent a lot of time debating whether the inability
+    to scale down as nicely as something like SQL has with sqlite
+    meant that it was out.
+
+    But I decided in the end that I really want MongoDB, not for
+    scalability, but for flexibility.  Schema evolution pains in SQL
+    are almost enough reason for me to want MongoDB, but not quite.
+    The real reason is because I want the ability to eventually handle
+    multiple media types through MediaGoblin, and also allow for
+    plugins, without the rigidity of tables making that difficult.  In
+    other words, something like::
+
+        {"title": "Me talking until you are bored",
+         "description": "blah blah blah",
+         "media_type": "audio",
+         "media_data": {
+             "length": "2:30",
+             "codec": "OGG Vorbis"},
+         "plugin_data": {
+             "licensing": {
+                 "license": "http://creativecommons.org/licenses/by-sa/3.0/"}}}
+
+
+    Being able to just dump media-specific information in a media_data
+    hashtable is pretty great, and even better is having a plugin
+    system where you can just let plugins have their own entire
+    key-value space cleanly inside the document that doesn't interfere
+    with anyone else's stuff.  If we were to let plugins to deposit
+    their own information inside the database, either we'd let plugins
+    create their own tables which makes SQL migrations even harder
+    than they already are, or we'd probably end up creating a table
+    with a column for key, a column for value, and a column for type
+    in one huge table called "plugin_data" or something similar.  (Yo
+    dawg, I heard you liked plugins, so I put a database in your
+    database so you can query while you query.)  Gross.
+
+    I also don't want things to be too loose so that we forget or lose
+    the structure of things, and that's one reason why I want to use
+    MongoKit, because we can cleanly define a much structure as we
+    want and verify that documents match that structure generally
+    without adding too much bloat or overhead (MongoKit is a pretty
+    lightweight wrapper and doesn't inject extra MongoKit-specific
+    stuff into the database, which is nice and nicer than many other
+    ORMs in that way).
+
+
+Why Sphinx for documentation
+============================
+
+Will Kahn-Greene on "Why Sphinx":
+
+    `Sphinx`_ is a fantastic tool for organizing documentation for a
+    Python-based project that makes it pretty easy to write docs that
+    are readable in source form and can be "compiled" into HTML, LaTeX
+    and other formats.
+
+    There are other doc systems out there, but given that GNU
+    MediaGoblin is being written in Python and I've done a ton of
+    documentation using Sphinx, it makes sense to use Sphinx for now.
+
+.. _Sphinx: http://sphinx.pocoo.org/
+
+
+Why AGPLv3 and CC0?
+===================
+
+Chris, Brett, Will, Rob, Matt, et al curated into a story where
+everyone is the hero by Will on "Why AGPLv3 and CC0":
+
+    The `AGPL v3`_ preserves the freedoms guaranteed by the GPL v3 in
+    the context of software as a service.  Using this license ensures
+    that users of the service have the ability to examine the source,
+    deploy their own instance, and implement their own version.  This
+    is really important to us and a core mission component of this
+    project.  Thus we decided that the software parts should be under
+    this license.
+
+    However, the project is made up of more than just software:
+    there's CSS, images, and other output-related things.  We wanted
+    the templates/images/css side of the project all permissive and
+    permissive in the same absolutely permissive way.  We're waiving
+    our copyrights to non-software things under the CC0 waiver.
+
+    That brings us to the templates where there's some code and some
+    output.  The template engine we're using is called Jinja2.  It
+    mixes HTML markup with Python code to render the output of the
+    software.  We decided the templates are part of the output of the
+    software and not the software itself.  We wanted the output of the
+    software to be licensed in a hassle-free way so that when someone
+    deploys their own GNU MediaGoblin instance with their own
+    templates, they don't have to deal with the copyleft aspects of
+    the AGPLv3 and we'd be fine with that because the changes they're
+    making are identity-related.  So at first we decided to waive our
+    copyrights to the templates with a CC0 waiver and then add an
+    exception to the AGPLv3 for the software such that the templates
+    can make calls into the software and yet be a separately licensed
+    work.  However, Brett brought up the question of whether this
+    allows some unscrupulous person to make changes to the software
+    through the templates in such a way that they're not bound by the
+    AGPLv3: i.e. a loophole.  We thought about this loophole and
+    between this and the extra legalese involved in the exception to
+    the AGPLv3, we decided that it's just way simpler if the templates
+    were also licensed under the AGPLv3.
+
+    Then we have the licensing for the documentation.  Given that the
+    documentation is tied to the software content-wise, we don't feel
+    like we have to worry about ensuring freedom of the documentation
+    or worry about attribution concerns.  Thus we're waiving our
+    copyrights to the documentation under CC0 as well.
+
+    Lastly, we have branding.  This covers logos and other things that
+    are distinctive to GNU MediaGoblin that we feel represents this
+    project.  Since we don't currently have any branding, this is an
+    open issue, but we're thinking we'll go with a CC BY-SA license.
+
+    By licensing in this way, we make sure that users of the software
+    receive the freedoms that the AGPLv3 ensures regardless of what
+    fate befalls this project.
+
+    So to summarize:
+
+    * software (Python, JavaScript, HTML templates): licensed
+      under AGPLv3
+    * non-software things (CSS, images, video): copyrights waived
+      under CC0 because this is output of the software
+    * documentation: copyrights waived under CC0 because it's not part
+      of the software
+    * branding assets: we're kicking this can down the road, but
+      probably CC BY-SA
+
+    This is all codified in the ``COPYING`` file.
+
+.. _AGPL v3: http://www.gnu.org/licenses/agpl.html
+.. _CC0 v1: http://creativecommons.org/publicdomain/zero/1.0/
+
+
+Why (non-mandatory) copyright assignment?
+=========================================
+
+Chris Webber on "Why copyright assignment?":
+
+    GNU MediaGoblin is a GNU project with non-mandatory but heavily
+    encouraged copyright assignment to the FSF.  Most, if not all, of
+    the core contributors to GNU MediaGoblin will have done a
+    copyright assignment, but unlike some other GNU projects, it isn't
+    required here.  We think this is the best choice for GNU
+    MediaGoblin: it ensures that the Free Software Foundation may
+    protect the software by enforcing the AGPL if the FSF sees fit,
+    but it also means that we can immediately merge in changes from a
+    new contributor.  It also means that some significant non-FSF
+    contributors might also be able to enforce the AGPL if seen fit.
+
+    Again, assignment is not mandatory, but it is heavily encouraged,
+    even incentivized: significant contributors who do a copyright
+    assignment to the FSF are eligible to have a unique goblin drawing
+    produced for them by the project's main founder, Christopher Allan
+    Webber.  See `the wiki <http://wiki.mediagoblin.org/>`_ for details.
+
+
diff --git a/docs/source/devel/storage.rst b/docs/source/devel/storage.rst
new file mode 100644
index 00000000..215f9579
--- /dev/null
+++ b/docs/source/devel/storage.rst
@@ -0,0 +1,125 @@
+=========
+ Storage
+=========
+
+The storage systems attached to your app
+----------------------------------------
+
+Dynamic content: queue_store and public_store
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Two instances of the StorageInterface come attached to your app. These 
+are: 
+
++ **queue_store:** When a user submits a fresh piece of media for
+  their gallery, before the Processing stage, that piece of media sits
+  here in the queue_store. (It's possible that we'll rename this to
+  "private_store" and start storing more non-publicly-stored stuff in
+  the future...). This is a StorageInterface implementation
+  instance. Visitors to your site probably cannot see it... it isn't
+  designed to be seen, anyway.
+
++ **public_store:** After your media goes through processing it gets
+  moved to the public store. This is also a StorageInterface
+  implelementation, and is for stuff that's intended to be seen by
+  site visitors.
+
+The workbench
+~~~~~~~~~~~~~
+
+In addition, there's a "workbench" used during
+processing...  it's just for temporary files during
+processing, and also for making local copies of stuff that
+might be on remote storage interfaces while transitionally
+moving/converting from the queue_store to the public store. 
+See the workbench module documentation for more.
+
+.. automodule:: mediagoblin.tools.workbench
+   :members:
+   :show-inheritance:
+
+
+Static assets / staticdirect
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On top of all that, there is some static media that comes bundled with your
+application. This stuff is kept in: 
+
+   mediagoblin/static/
+
+These files are for mediagoblin base assets. Things like the CSS files, 
+logos, etc. You can mount these at whatever location is appropriate to you
+(see the direct_remote_path option in the config file) so if your users 
+are keeping their static assets at http://static.mgoblin.example.org/ but 
+their actual site is at http://mgoblin.example.org/, you need to be able 
+to get your static files in a where-it's-mounted agnostic way. There's a 
+"staticdirector" attached to the request object. It's pretty easy to use;
+just look at this bit taken from the 
+mediagoblin/templates/mediagoblin/base.html main template:
+
+    <link rel="stylesheet" type="text/css" 
+        href="Template:Request.staticdirect('/css/extlib/text.css')"/>
+
+see? Not too hard. As expected, if you configured direct_remote_path to be 
+http://static.mgoblin.example.org/ you'll get back 
+http://static.mgoblin.example.org/css/extlib/text.css just as you'd 
+probably expect. 
+
+StorageInterface and implementations
+------------------------------------
+
+The guts of StorageInterface and friends 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+So, the StorageInterface!
+
+So, the public and queue stores both use StorageInterface implementations
+... but what does that mean? It's not too hard.
+
+Open up: 
+
+    mediagoblin/storage.py
+
+In here you'll see a couple of things. First of all, there's the 
+StorageInterface class. What you'll see is that this is just a very simple
+python class. A few of the methods actually implement things, but for the
+most part, they don't. What really matters about this class is the 
+docstrings. Each expected method is documented as to how it should be 
+constructed. Want to make a new StorageInterface? Simply subclass it. Want 
+to know how to use the methods of your storage system? Read these docs, 
+they span all implementations.
+
+There are a couple of implementations of these classes bundled in 
+storage.py as well. The most simple of these is BasicFileStorage, which is 
+also the default storage system used. As expected, this stores files 
+locally on your machine.
+
+There's also a CloudFileStorage system. This provides a mapping to 
+[OpenStack's swift http://swift.openstack.org/] storage system (used by 
+RackSpace Cloud files and etc).
+
+Between these two examples you should be able to get a pretty good idea of
+how to write your own storage systems, for storing data across your 
+beowulf cluster of radioactive monkey brains, whatever. 
+
+Writing code to store stuff
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+So what does coding for StorageInterface implementations actually look 
+like? It's pretty simple, really. For one thing, the design is fairly 
+inspired by [Django's file storage API 
+https://docs.djangoproject.com/en/dev/ref/files/storage/]... with some 
+differences.
+
+Basically, you access files on "file paths", which aren't exactly like 
+unix file paths, but are close. If you wanted to store a file on a path 
+like dir1/dir2/filename.jpg you'd actually write that file path like:
+
+['dir1', 'dir2', 'filename.jpg']
+
+This way we can be *sure* that each component is actually a component of
+the path that's expected... we do some filename cleaning on each component.
+
+Your StorageInterface should pass in and out "file like objects". In other 
+words, they should provide .read() and .write() at minimum, and probably 
+also .seek() and .close(). 
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 00000000..d71f39f8
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,100 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+
+===========================================
+Welcome to GNU MediaGoblin's documentation!
+===========================================
+
+GNU MediaGoblin is a platform for sharing photos, video and other media
+in an environment that respects our freedom and independence.
+
+This is a Free Software project. It is built by contributors for all
+to use and enjoy. If you're intrested in contributing, see `the wiki
+<http://wiki.mediagoblin.org/>`_ which has pages that talk about the
+ways someone can contribute.
+
+
+Part 1: Site Administrator's Guide
+==================================
+
+This guide covers installing, configuring, deploying and running a GNU
+MediaGoblin website.  It is written for site administrators.
+
+.. toctree::
+   :maxdepth: 1
+
+   siteadmin/foreword
+   siteadmin/about
+   siteadmin/deploying
+   siteadmin/production-deployments
+   siteadmin/configuration
+   siteadmin/media-types
+   siteadmin/help
+   siteadmin/relnotes
+   siteadmin/theming
+   siteadmin/plugins
+
+
+.. _core-plugin-section:
+
+Part 2: Core plugin documentation
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   plugindocs/flatpagesfile
+   plugindocs/sampleplugin
+   plugindocs/oauth
+   plugindocs/trim_whitespace
+   plugindocs/raven
+
+
+Part 3: Plugin Writer's Guide
+=============================
+
+This guide covers writing new GNU MediaGoblin plugins.
+
+.. toctree::
+   :maxdepth: 1
+
+   pluginwriter/foreward
+   pluginwriter/quickstart
+   pluginwriter/database
+   pluginwriter/api
+   pluginwriter/tests
+
+
+Part 4: Developer's Zone
+========================
+
+This chapter contains various information for developers.
+
+.. toctree::
+   :maxdepth: 1
+
+   devel/codebase
+   devel/storage
+   devel/originaldesigndecisions
+
+
+Indices and tables
+==================
+
+* :ref:`search`
+* :ref:`genindex`
+
+.. * :ref:`modindex`
+
+This guide was built on |today|.
diff --git a/docs/source/plugindocs/flatpagesfile.rst b/docs/source/plugindocs/flatpagesfile.rst
new file mode 100644
index 00000000..68965fda
--- /dev/null
+++ b/docs/source/plugindocs/flatpagesfile.rst
@@ -0,0 +1 @@
+.. include:: ../../../mediagoblin/plugins/flatpagesfile/README.rst
diff --git a/docs/source/plugindocs/oauth.rst b/docs/source/plugindocs/oauth.rst
new file mode 100644
index 00000000..0685c9d1
--- /dev/null
+++ b/docs/source/plugindocs/oauth.rst
@@ -0,0 +1 @@
+.. include:: ../../../mediagoblin/plugins/oauth/README.rst
diff --git a/docs/source/plugindocs/raven.rst b/docs/source/plugindocs/raven.rst
new file mode 100644
index 00000000..71e284d0
--- /dev/null
+++ b/docs/source/plugindocs/raven.rst
@@ -0,0 +1,2 @@
+.. _raven-setup: Set up the raven plugin
+.. include:: ../../../mediagoblin/plugins/raven/README.rst
diff --git a/docs/source/plugindocs/sampleplugin.rst b/docs/source/plugindocs/sampleplugin.rst
new file mode 100644
index 00000000..aa04e4e9
--- /dev/null
+++ b/docs/source/plugindocs/sampleplugin.rst
@@ -0,0 +1 @@
+.. include:: ../../../mediagoblin/plugins/sampleplugin/README.rst
diff --git a/docs/source/plugindocs/trim_whitespace.rst b/docs/source/plugindocs/trim_whitespace.rst
new file mode 100644
index 00000000..eb38e0e5
--- /dev/null
+++ b/docs/source/plugindocs/trim_whitespace.rst
@@ -0,0 +1 @@
+.. include:: ../../../mediagoblin/plugins/trim_whitespace/README.rst
diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst
new file mode 100644
index 00000000..66def173
--- /dev/null
+++ b/docs/source/pluginwriter/api.rst
@@ -0,0 +1,296 @@
+.. MediaGoblin Documentation
+
+   Written in 2013 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+.. _plugin-api-chapter:
+
+==========
+Plugin API
+==========
+
+This documents the general plugin API.
+
+Please note, at this point OUR PLUGIN HOOKS MAY AND WILL CHANGE.
+Authors are encouraged to develop plugins and work with the
+MediaGoblin community to keep them up to date, but this API will be a
+moving target for a few releases.
+
+Please check the :ref:`release-notes` for updates!
+
+
+How are hooks added?  Where do I find them?
+-------------------------------------------
+
+Much of this document talks about hooks, both as in terms of regular
+hooks and template hooks.  But where do they come from, and how can
+you find a list of them?
+
+For the moment, the best way to find available hooks is to check the
+source code itself.  (Yes, we should start a more official hook
+listing with descriptions soon.)  But many hooks you may need do not
+exist yet: what to do then?
+
+The plan at present is that we are adding hooks as people need them,
+with community discussion.  If you find that you need a hook and
+MediaGoblin at present doesn't provide it at present, please
+`http://mediagoblin.org/pages/join.html <talk to us>`_!  We'll
+evaluate what to do from there.
+
+
+:mod:`pluginapi` Module
+-----------------------
+
+.. automodule:: mediagoblin.tools.pluginapi
+   :members: get_config, register_routes, register_template_path,
+             register_template_hooks, get_hook_templates,
+             hook_handle, hook_runall, hook_transform
+
+Configuration
+-------------
+
+Your plugin may define its own configuration defaults.
+
+Simply add to the directory of your plugin a config_spec.ini file.  An
+example might look like::
+
+  [plugin_spec]
+  some_string = string(default="blork")
+  some_int = integer(default=50)
+
+This means that when people enable your plugin in their config you'll
+be able to provide defaults as well as type validation.
+
+
+Context Hooks
+-------------
+
+View specific hooks
++++++++++++++++++++
+
+You can hook up to almost any template called by any specific view
+fairly easily.  As long as the view directly or indirectly uses the
+method ``render_to_response`` you can access the context via a hook
+that has a key in the format of the tuple::
+
+  (view_symbolic_name, view_template_path)
+
+Where the "view symbolic name" is the same parameter used in
+``request.urlgen()`` to look up the view.  So say we're wanting to add
+something to the context of the user's homepage.  We look in
+mediagoblin/user_pages/routing.py and see::
+
+  add_route('mediagoblin.user_pages.user_home',
+            '/u/<string:user>/',
+            'mediagoblin.user_pages.views:user_home')
+
+Aha!  That means that the name is ``mediagoblin.user_pages.user_home``.
+Okay, so then we look at the view at the
+``mediagoblin.user_pages.user_home`` method::
+
+  @uses_pagination
+  def user_home(request, page):
+      # [...] whole bunch of stuff here
+      return render_to_response(
+          request,
+          'mediagoblin/user_pages/user.html',
+          {'user': user,
+           'user_gallery_url': user_gallery_url,
+           'media_entries': media_entries,
+           'pagination': pagination})
+
+Nice!  So the template appears to be
+``mediagoblin/user_pages/user.html``.  Cool, that means that the key
+is::
+
+  ("mediagoblin.user_pages.user_home",
+   "mediagoblin/user_pages/user.html")
+
+The context hook uses ``hook_transform()`` so that means that if we're
+hooking into it, our hook will both accept one argument, ``context``,
+and should return that modified object, like so::
+
+  def add_to_user_home_context(context):
+      context['foo'] = 'bar'
+      return context
+  
+  hooks = {
+      ("mediagoblin.user_pages.user_home",
+       "mediagoblin/user_pages/user.html"): add_to_user_home_context}
+
+
+Global context hooks
+++++++++++++++++++++
+
+If you need to add something to the context of *every* view, it is not
+hard; there are two hooks hook that also uses hook_transform (like the
+above) but make available what you are providing to *every* view.
+
+Note that there is a slight, but critical, difference between the two.
+
+The most general one is the ``'template_global_context'`` hook.  This
+one is run only once, and is read into the global context... all views
+will get access to what are in this dict.
+
+The slightly more expensive but more powerful one is
+``'template_context_prerender'``.  This one is not added to the global
+context... it is added to the actual context of each individual
+template render right before it is run!  Because of this you also can
+do some powerful and crazy things, such as checking the request object
+or other parts of the context before passing them on.
+
+
+Adding static resources
+-----------------------
+
+It's possible to add static resources for your plugin.  Say your
+plugin needs some special javascript and images... how to provide
+them?  Then how to access them?  MediaGoblin has a way!
+
+
+Attaching to the hook
++++++++++++++++++++++
+
+First, you need to register your plugin's resources with the hook.
+This is pretty easy actually: you just need to provide a function that
+passes back a PluginStatic object.
+
+.. autoclass:: mediagoblin.tools.staticdirect.PluginStatic
+
+
+Running plugin assetlink
+++++++++++++++++++++++++
+
+In order for your plugin assets to be properly served by MediaGoblin,
+your plugin's asset directory needs to be symlinked into the directory
+that plugin assets are served from.  To set this up, run::
+
+  ./bin/gmg assetlink
+
+
+Using staticdirect
+++++++++++++++++++
+
+Once you have this, you will want to be able to of course link to your
+assets!  MediaGoblin has a "staticdirect" tool; you want to use this
+like so in your templates::
+
+  staticdirect("css/monkeys.css", "mystaticname")
+
+Replace "mystaticname" with the name you passed to PluginStatic.  The
+staticdirect method is, for convenience, attached to the request
+object, so you can access this in your templates like:
+
+.. code-block:: html
+
+  <img alt="A funny bunny"
+       src="{{ request.staticdirect('images/funnybunny.png', 'mystaticname') }}" />
+
+
+Additional hook tips
+--------------------
+
+This section aims to explain some tips in regards to adding hooks to
+the MediaGoblin repository.
+
+WTForms hooks
++++++++++++++
+
+We haven't totally settled on a way to tranform wtforms form objects,
+but here's one way.  In your view::
+
+  from mediagoblin.foo.forms import SomeForm
+
+  def some_view(request)
+      form_class = hook_transform('some_form_transform', SomeForm)
+      form = form_class(request.form)
+
+Then to hook into this form, do something in your plugin like::
+
+  import wtforms
+
+  class SomeFormAdditions(wtforms.Form):
+      new_datefield = wtforms.DateField()
+
+  def transform_some_form(orig_form):
+      class ModifiedForm(orig_form, SomeFormAdditions)
+      return ModifiedForm
+
+  hooks = {
+      'some_form_transform': transform_some_form}
+
+
+Interfaces
+++++++++++
+
+If you want to add a pseudo-interface, it's not difficult to do so.
+Just write the interface like so::
+
+  class FrobInterface(object):
+      """
+      Interface for Frobbing.
+
+      Classes implementing this interface should provide defrob and frob.
+      They may also implement double_frob, but it is not required; if
+      not provided, we will use a general technique.
+      """
+
+      def defrob(self, frobbed_obj):
+          """
+          Take a frobbed_obj and defrob it.  Returns the defrobbed object.
+          """
+          raise NotImplementedError()
+      
+      def frob(self, normal_obj):
+          """
+          Take a normal object and frob it.  Returns the frobbed object.
+          """
+          raise NotImplementedError()
+
+      def double_frob(self, normal_obj):
+          """
+          Frob this object and return it multiplied by two.
+          """
+          return self.frob(normal_obj) * 2
+
+
+  def some_frob_using_method():
+      # something something something
+      frobber = hook_handle(FrobInterface)
+      frobber.frob(blah)
+
+      # alternately you could have a default
+      frobber = hook_handle(FrobInterface) or DefaultFrobber
+      frobber.defrob(foo)
+
+
+It's fine to use your interface as the key instead of a string if you
+like.  (Usually this is messy, but since interfaces are public and
+since you need to import them into your plugin anyway, interfaces
+might as well be keys.)
+
+Then a plugin providing your interface can be like::
+
+  from mediagoblin.foo.frobfrogs import FrobInterface
+  from frogfrobber import utils
+
+  class FrogFrobber(FrobInterface):
+      """
+      Takes a frogputer science approach to frobbing.
+      """
+      def defrob(self, frobbed_obj):
+          return utils.frog_defrob(frobbed_obj)
+
+      def frob(self, normal_obj):
+          return utils.frog_frob(normal_obj)
+
+   hooks = {
+       FrobInterface: lambda: return FrogFrobber}
diff --git a/docs/source/pluginwriter/database.rst b/docs/source/pluginwriter/database.rst
new file mode 100644
index 00000000..603a19eb
--- /dev/null
+++ b/docs/source/pluginwriter/database.rst
@@ -0,0 +1,114 @@
+.. MediaGoblin Documentation
+
+   Written in 2013 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+
+.. _plugin-database-chapter:
+
+
+===========================
+Database models for plugins
+===========================
+
+
+Accessing Existing Data
+=======================
+
+If your plugin wants to access existing data, this is quite
+straight forward. Just import the appropiate models and use
+the full power of SQLAlchemy. Take a look at the (upcoming)
+database section in the Developer's Chapter.
+
+
+Creating new Tables
+===================
+
+If your plugin needs some new space to store data, you
+should create a new table.  Please do not modify core
+tables.  Not doing so might seem inefficient and possibly
+is.  It will help keep things sane and easier to upgrade
+versions later.
+
+So if you create a new plugin and need new tables, create a
+file named ``models.py`` in your plugin directory. You
+might take a look at the core's db.models for some ideas.
+Here's a simple one:
+
+.. code-block:: python
+
+    from mediagoblin.db.base import Base
+    from sqlalchemy import Column, Integer, Unicode, ForeignKey
+
+    class MediaSecurity(Base):
+        __tablename__ = "yourplugin__media_security"
+
+        # The primary key *and* reference to the main media_entry
+        media_entry = Column(Integer, ForeignKey('core__media_entries.id'),
+            primary_key=True)
+        get_media_entry = relationship("MediaEntry",
+            backref=backref("security_rating", cascade="all, delete-orphan"))
+
+        rating = Column(Unicode)
+
+    MODELS = [MediaSecurity]
+
+That's it.
+
+Some notes:
+
+* Make sure all your ``__tablename__`` start with your
+  plugin's name so the tables of various plugins can't
+  conflict in the database. (Conflicts in python naming are
+  much easier to fix later).
+* Try to get your database design as good as possible in
+  the first attempt.  Changing the database design later,
+  when people already have data using the old design, is
+  possible (see next chapter), but it's not easy.
+
+
+Changing the Database Schema Later
+==================================
+
+If your plugin is in use and instances use it to store some
+data, changing the database design is a tricky thing.
+
+1. Make up your mind how the new schema should look like.
+2. Change ``models.py`` to contain the new schema. Keep a
+   copy of the old version around for your personal
+   reference later.
+3. Now make up your mind (possibly using your old and new
+   ``models.py``) what steps in SQL are needed to convert
+   the old schema to the new one.
+   This is called a "migration".
+4. Create a file ``migrations.py`` that will contain all
+   your migrations and add your new migration.
+
+Take a look at the core's ``db/migrations.py`` for some
+good examples on what you might be able to do. Here's a
+simple one to add one column:
+
+.. code-block:: python
+
+    from mediagoblin.db.migration_tools import RegisterMigration, inspect_table
+    from sqlalchemy import MetaData, Column, Integer
+
+    MIGRATIONS = {}
+
+    @RegisterMigration(1, MIGRATIONS)
+    def add_license_preference(db):
+        metadata = MetaData(bind=db.bind)
+
+        security_table = inspect_table(metadata, 'yourplugin__media_security')
+
+        col = Column('security_level', Integer)
+        col.create(security_table)
+        db.commit()
diff --git a/docs/source/pluginwriter/foreward.rst b/docs/source/pluginwriter/foreward.rst
new file mode 100644
index 00000000..fd3a0c22
--- /dev/null
+++ b/docs/source/pluginwriter/foreward.rst
@@ -0,0 +1,43 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+========
+Foreword
+========
+
+About the Plugin Writer's Guide
+===============================
+
+This guide covers writing plugins for GNU MediaGoblin. It's very much
+a work in progress partially because we just started writing it and
+partially because the plugin API is currently in flux.
+
+
+Improving the Plugin Writer's Guide
+===================================
+
+There are a few ways---please pick whichever method is convenient for
+you!
+
+1. Write up a bug report in the bug tracker
+2. Tell someone on IRC ``#mediagoblin`` on Freenode.
+3. Write an email to the devel mailing list.
+
+Information about the bugtracker, IRC and the mailing list is all on
+the `join page`_.
+
+.. _join page: http://mediagoblin.org/join/
+
+Patches are the most helpful, but even feedback on what you think
+could be improved and how to improve it is also helpful.
+
diff --git a/docs/source/pluginwriter/quickstart.rst b/docs/source/pluginwriter/quickstart.rst
new file mode 100644
index 00000000..6d45ea36
--- /dev/null
+++ b/docs/source/pluginwriter/quickstart.rst
@@ -0,0 +1,188 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+
+===========
+Quick Start
+===========
+
+This is a quick start. It's not comprehensive, but it walks through
+writing a basic plugin called "sampleplugin" which logs "I've been
+started!" when ``setup_plugin()`` has been called.
+
+.. todo: Rewrite this to be a useful plugin
+
+
+Step 1: Files and directories
+=============================
+
+GNU MediaGoblin plugins are Python projects at heart. As such, you should
+use a standard Python project directory tree::
+
+    sampleplugin/
+     |- README
+     |- LICENSE
+     |- setup.py
+     |- sampleplugin/
+        |- __init__.py
+
+
+The outer ``sampleplugin`` directory holds all the project files.
+
+The ``README`` should cover what your plugin does, how to install it,
+how to configure it, and all the sorts of things a README should
+cover.
+
+The ``LICENSE`` should have the license under which you're
+distributing your plugin.
+
+The inner ``sampleplugin`` directory is the Python package that holds
+your plugin's code.
+
+The ``__init__.py`` denotes that this is a Python package. It also
+holds the plugin code and the ``hooks`` dict that specifies which
+hooks the sampleplugin uses.
+
+
+Step 2: README
+==============
+
+Here's a rough ``README``. Generally, you want more information
+because this is the file that most people open when they want to learn
+more about your project.
+
+::
+
+    README
+    ======
+
+    This is a sample plugin. It logs a line when ``setup__plugin()`` is
+    run.
+
+
+Step 3: LICENSE
+===============
+
+GNU MediaGoblin plugins must be licensed under the AGPLv3 or later. So
+the LICENSE file should be the AGPLv3 text which you can find at
+`<http://www.gnu.org/licenses/agpl-3.0.html>`_
+
+
+Step 4: setup.py
+================
+
+This file is used for packaging and distributing your plugin.
+
+We'll use a basic one::
+
+    from setuptools import setup, find_packages
+
+    setup(
+        name='sampleplugin',
+        version='1.0',
+        packages=find_packages(),
+        include_package_data=True,
+        install_requires=[],
+        license='AGPLv3',
+        )
+
+
+See `<http://docs.python.org/distutils/index.html#distutils-index>`_
+for more details.
+
+
+Step 5: the code
+================
+
+The code for ``__init__.py`` looks like this:
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 12,23
+
+    import logging
+    from mediagoblin.tools.pluginapi import Plugin, get_config
+
+
+    # This creates a logger that you can use to log information to
+    # the console or a log file.
+    _log = logging.getLogger(__name__)
+
+
+    # This is the function that gets called when the setup
+    # hook fires.
+    def setup_plugin():
+        _log.info("I've been started!")
+        config = get_config('sampleplugin')
+        if config:
+            _log.info('%r' % config)
+        else:
+            _log.info('There is no configuration set.')
+
+
+    # This is a dict that specifies which hooks this plugin uses.
+    # This one only uses one hook: setup.
+    hooks = {
+        'setup': setup_plugin
+        }
+
+
+Line 12 defines the ``setup_plugin`` function.
+
+Line 23 defines ``hooks``. When MediaGoblin loads this file, it sees
+``hooks`` and registers all the callables with their respective hooks.
+
+
+Step 6: Installation and configuration
+======================================
+
+To install the plugin for development, you need to make sure it's
+available to the Python interpreter that's running MediaGoblin.
+
+There are a couple of ways to do this, but we're going to pick the
+easy one.
+
+Use ``python`` from your MediaGoblin virtual environment and do::
+
+    python setup.py develop
+
+Any changes you make to your plugin will be available in your
+MediaGoblin virtual environment.
+
+Then adjust your ``mediagoblin.ini`` file to load the plugin::
+
+    [plugins]
+
+    [[sampleplugin]]
+
+
+Step 7: That's it!
+==================
+
+When you launch MediaGoblin, it'll load the plugin and you'll see
+evidence of that in the log file.
+
+That's it for the quick start!
+
+
+Where to go from here
+=====================
+
+See the documentation on the :ref:`plugin-api-chapter` for code
+samples and other things you can use when building your plugin.  If
+your plugin needs its own database models, see
+:ref:`plugin-database-chapter`.
+
+See `Hitchhiker's Guide to Packaging
+<http://guide.python-distribute.org/>`_ for more information on
+packaging your plugin.
diff --git a/docs/source/pluginwriter/tests.rst b/docs/source/pluginwriter/tests.rst
new file mode 100644
index 00000000..fe99688f
--- /dev/null
+++ b/docs/source/pluginwriter/tests.rst
@@ -0,0 +1,64 @@
+.. MediaGoblin Documentation
+
+   Written in 2013 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+==============================
+Writing unit tests for plugins
+==============================
+
+Here's a brief guide to writing unit tests for plugins.  However, it
+isn't really ideal.  It also hasn't been well tested... yes, there's
+some irony there :)
+
+Some notes: we're using py.test and webtest for unit testing stuff.
+Keep that in mind.
+
+My suggestion is to mime the behavior of `mediagoblin/tests/` and put
+that in your own plugin, like `myplugin/tests/`.  Copy over
+`conftest.py` and `pytest.ini` to your tests directory, but possibly
+change the `test_app` fixture to match your own tests' config needs.
+For example::
+
+  import pkg_resources
+  # [...]
+
+  @pytest.fixture()
+  def test_app(request):
+      return get_app(
+          request,
+          mgoblin_config=pkg_resources.resource_filename(
+              'myplugin.tests', 'myplugin_mediagoblin.ini'))
+
+In any test module in your tests directory you can then do::
+
+  def test_somethingorother(test_app):
+      # real code goes here
+      pass
+
+And you'll get a mediagoblin application wrapped in webtest passed in
+to your environment.
+
+If your plugin needs to define multiple configuration setups, you can
+actually set up multiple fixtures very easily for this.  You can just
+set up multiple fixtures with different names that point to different
+configs and pass them in as that named argument.
+
+To run the tests, from mediagoblin's directory (make sure that your
+plugin has been added to your mediagoblin checkout's virtualenv!) do::
+
+  ./runtests.sh /path/to/myplugin/tests/
+
+replacing `/path/to/myplugin/` with the actual path to your plugin.
+
+NOTE: again, the above is untested, but it should probably work.  If
+you run into trouble, `contact us
+<http://mediagoblin.org/pages/join.html>`_, preferably on IRC!
diff --git a/docs/source/siteadmin/about.rst b/docs/source/siteadmin/about.rst
new file mode 100644
index 00000000..f9602397
--- /dev/null
+++ b/docs/source/siteadmin/about.rst
@@ -0,0 +1,102 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+=======================
+ About GNU MediaGoblin
+=======================
+
+.. contents:: Sections
+   :local:
+
+
+What is GNU MediaGoblin?
+========================
+
+In 2008, a number of free software developers and activists gathered
+at the FSF to attempt to answer the question "What should software
+freedom look like on the participatory web?" Their answer, the
+`Franklin Street Statement`_ has lead to the development of
+`autonomo.us`_ community, and free software projects including
+`Identi.ca`_ and `Libre.fm`_.
+
+.. _Franklin Street Statement: http://autonomo.us/2008/07/franklin-street-statement/
+.. _autonomo.us: http://autonomo.us/
+.. _identi.ca: http://identi.ca/
+.. _Libre.fm: http://libre.fm/
+
+Identi.ca and Libre.fm address the need for micro-blogging and music
+sharing services and software that respect users' freedom and
+autonomy.
+
+GNU MediaGoblin emerges from this milieu to create a platform for us to share
+photos, video and other media in an environment that respects our freedom and
+independence.  In the future MediaGoblin will provide tools to facilitate
+collaboration on media projects.
+
+
+Why Build GNU MediaGoblin?
+==========================
+
+The Internet is designed---and works best---as a complex and endlessly
+resilient network.  When key services and media outlets are
+concentrated in centralized platforms, the network becomes less useful
+and increasingly fragile.  As always, the proprietary nature of these
+systems, hinders users ability to develop, extend, and understand
+their software; however, in the case of network services it also means
+that users must forfeit control of their data to the service
+providers.
+
+Therefore, we believe that network services must be federated to avoid
+centralization and that everyone ought to have control over their
+data.  In support of this, we've decided to help build the tools to
+make these kinds of services possible.  We hope you'll join us, both
+as users and as contributors.
+
+
+Who Contributes to the Project?
+===============================
+
+You do!
+
+We are free software activists and folks who have worked on a variety
+of other projects including: Libre.fm, GNU Social, Status.net, Miro,
+Miro Community, and OpenHatch among others.  We're programmers,
+musicians, writers, and painters.  We're friendly and dedicated to
+software and network freedom.
+
+
+How Can I Participate?
+======================
+
+See `Get Involved <http://mediagoblin.org/join/>`_ on the website.  We
+eagerly look forward to seeing you!
+
+
+How is GNU MediaGoblin licensed?
+================================
+
+GNU MediaGoblin software is released under an AGPLv3 license.
+
+See the ``COPYING`` file in the root of the source for details.
+
+
+Is MediaGoblin an official GNU project?  What does that mean?
+=============================================================
+
+MediaGoblin is an official GNU project! This status means that we the
+meet the GNU Project's rigorous standards for free software.  To find
+out more about what that means, check out the `GNU website`_.
+
+Please feel free to contact us with further questions!
+
+.. _GNU website: http://gnu.org/
diff --git a/docs/source/siteadmin/configuration.rst b/docs/source/siteadmin/configuration.rst
new file mode 100644
index 00000000..3da5cdd9
--- /dev/null
+++ b/docs/source/siteadmin/configuration.rst
@@ -0,0 +1,131 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+.. _configuration-chapter:
+
+========================
+Configuring MediaGoblin
+========================
+
+So!  You've got MediaGoblin up and running, but you need to adjust
+some configuration parameters.  Well you've come to the right place!
+
+
+MediaGoblin's config files
+==========================
+
+When configuring MediaGoblin, there are two files you might want to
+make local modified versions of, and one extra file that might be
+helpful to look at.  Let's examine these.
+
+mediagoblin.ini
+  This is the config file for MediaGoblin, the application.  If you want to
+  tweak settings for MediaGoblin, you'll usually tweak them here.
+
+paste.ini
+  This is primarily a server configuration file, on the Python side
+  (specifically, on the WSGI side, via `paste deploy
+  <http://pythonpaste.org/deploy/>`_ / `paste script
+  <http://pythonpaste.org/script/>`_).  It also sets up some
+  middleware that you can mostly ignore, except to configure
+  sessions... more on that later.  If you are adding a different
+  Python server other than fastcgi / plain HTTP, you might configure
+  it here.  You probably won't need to change this file very much.
+
+
+There's one more file that you certainly won't change unless you're
+making coding contributions to mediagoblin, but which can be useful to
+read and reference:
+
+mediagoblin/config_spec.ini
+  This file is actually a specification for mediagoblin.ini itself, as
+  a config file!  It defines types and defaults.  Sometimes it's a
+  good place to look for documentation... or to find that hidden
+  option that we didn't tell you about. :)
+
+
+Making local copies
+===================
+
+Let's assume you're doing the virtualenv setup described elsewhere in this
+manual, and you need to make local tweaks to the config files. How do you do 
+that? Let's see.
+
+To make changes to mediagoblin.ini ::
+
+    cp mediagoblin.ini mediagoblin_local.ini
+
+To make changes to paste.ini ::
+
+    cp paste.ini paste_local.ini
+
+From here you should be able to make direct adjustments to the files,
+and most of the commands described elsewhere in this manual will "notice"
+your local config files and use those instead of the non-local version.
+
+.. note::
+
+   Note that all commands provide a way to pass in a specific config
+   file also, usually by a ``-cf`` flag.
+
+
+Common changes
+==============
+
+Enabling email notifications
+----------------------------
+
+You'll almost certainly want to enable sending email.  By default,
+MediaGoblin doesn't really do this... for the sake of developer
+convenience, it runs in "email debug mode".
+
+To make MediaGoblin send email, you need a mailer daemon.
+
+Change this in your ``mediagoblin.ini`` file::
+
+    email_debug_mode = false
+
+You should also change the "from" email address by setting
+``email_sender_address``. For example::
+
+    email_sender_address = "foo@example.com"
+
+If you have more custom SMTP settings, you also have the following
+options at your disposal, which are all optional, and do exactly what
+they sound like.
+
+- email_smtp_host
+- email_smtp_port
+- email_smtp_user
+- email_smtp_pass
+
+
+All other configuration changes
+-------------------------------
+
+To be perfectly honest, there are quite a few options and we haven't had
+time to document them all.
+
+So here's a cop-out section saying that if you get into trouble, hop
+onto IRC and we'll help you out.  Details for the IRC channel is on the
+`join page`_ of the website.
+
+.. _join page: http://mediagoblin.org/join/
+
+
+
+
+Celery
+======
+
+FIXME: List Celery configuration here.
diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst
new file mode 100644
index 00000000..0ee6b5b4
--- /dev/null
+++ b/docs/source/siteadmin/deploying.rst
@@ -0,0 +1,390 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+.. _deploying-chapter:
+
+=====================
+Deploying MediaGoblin
+=====================
+
+GNU MediaGoblin is fairly new and so at the time of writing, there
+aren't easy package-manager-friendly methods to install MediaGoblin.
+However, doing a basic install isn't too complex in and of itself.
+
+There's an almost infinite way to deploy things... for now, we'll keep
+it simple with some assumptions and use a setup that combines
+mediagoblin + virtualenv + fastcgi + nginx on a .deb or .rpm based
+GNU/Linux distro.
+
+.. note::
+
+   These tools are for site administrators wanting to deploy a fresh
+   install.  If instead you want to join in as a contributor, see our
+   `Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_ instead.
+
+   There are also many ways to install servers... for the sake of
+   simplicity, our instructions below describe installing with nginx.
+   For more recipes, including Apache, see
+   `our wiki <http://wiki.mediagoblin.org/Deployment>`_.
+
+Prepare System
+--------------
+
+Dependencies
+~~~~~~~~~~~~
+
+MediaGoblin has the following core dependencies:
+
+- Python 2.6 or 2.7
+- `python-lxml <http://lxml.de/>`_
+- `git <http://git-scm.com/>`_
+- `SQLite <http://www.sqlite.org/>`_/`PostgreSQL <http://www.postgresql.org/>`_
+- `Python Imaging Library <http://www.pythonware.com/products/pil/>`_  (PIL)
+- `virtualenv <http://www.virtualenv.org/>`_
+
+On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and
+derivatives) issue the following command::
+
+    sudo apt-get install git-core python python-dev python-lxml \
+        python-imaging python-virtualenv
+
+On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the
+following command::
+
+    yum install python-paste-deploy python-paste-script \
+        git-core python python-devel python-lxml python-imaging \
+        python-virtualenv
+
+Configure PostgreSQL
+~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+   MediaGoblin currently supports PostgreSQL and SQLite. The default is a
+   local SQLite database. This will "just work" for small deployments.
+
+   For medium to large deployments we recommend PostgreSQL.
+
+   If you don't want/need postgres, skip this section.
+
+These are the packages needed for Debian Wheezy (testing)::
+
+    sudo apt-get install postgresql postgresql-client python-psycopg2
+
+The installation process will create a new *system* user named ``postgres``,
+it will have privilegies sufficient to manage the database. We will create a
+new database user with restricted privilegies and a new database owned by our
+restricted database user for our MediaGoblin instance.
+
+In this example, the database user will be ``mediagoblin`` and the database
+name will be ``mediagoblin`` too.
+
+To create our new user, run::
+
+    sudo -u postgres createuser mediagoblin
+
+then answer NO to *all* the questions::
+
+    Shall the new role be a superuser? (y/n) n
+    Shall the new role be allowed to create databases? (y/n) n
+    Shall the new role be allowed to create more new roles? (y/n) n
+
+then create the database all our MediaGoblin data should be stored in::
+
+    sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin
+
+where the first ``mediagoblin`` is the database owner and the second
+``mediagoblin`` is the database name.
+
+.. caution:: Where is the password?
+
+    These steps enable you to authenticate to the database in a password-less
+    manner via local UNIX authentication provided you run the MediaGoblin
+    application as a user with the same name as the user you created in
+    PostgreSQL.
+
+    More on this in :ref:`Drop Privileges for MediaGoblin <drop-privileges-for-mediagoblin>`.
+
+
+.. _drop-privileges-for-mediagoblin:
+
+Drop Privileges for MediaGoblin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As MediaGoblin does not require special permissions or elevated
+access, you should run MediaGoblin under an existing non-root user or
+preferably create a dedicated user for the purpose of running
+MediaGoblin. Consult your distribution's documentation on how to
+create "system account" or dedicated service user. Ensure that it is
+not possible to log in to your system with as this user.
+
+You should create a working directory for MediaGoblin. This document
+assumes your local git repository will be located at 
+``/srv/mediagoblin.example.org/mediagoblin/`` for this documentation.
+Substitute your prefer ed local deployment path as needed.
+
+This document assumes that all operations are performed as this
+user. To drop privileges to this user, run the following command::
+
+      su - [mediagoblin]
+
+Where, "``[mediagoblin]``" is the username of the system user that will
+run MediaGoblin.
+
+Install MediaGoblin and Virtualenv
+----------------------------------
+
+.. note::
+
+   MediaGoblin is still developing rapidly. As a result
+   the following instructions recommend installing from the ``master``
+   branch of the git repository. Eventually production deployments will
+   want to transition to running from more consistent releases.
+
+Issue the following commands, to create and change the working
+directory. Modify these commands to reflect your own environment::
+
+    mkdir -p /srv/mediagoblin.example.org/
+    cd /srv/mediagoblin.example.org/
+
+Clone the MediaGoblin repository::
+
+    git clone git://gitorious.org/mediagoblin/mediagoblin.git
+
+And set up the in-package virtualenv::
+
+    cd mediagoblin
+    (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop
+
+.. note::
+
+   If you have problems here, consider trying to install virtualenv
+   with the ``--distribute`` or ``--no-site-packages`` options. If
+   your system's default Python is in the 3.x series you may need to
+   run ``virtualenv`` with the  ``--python=python2.7`` or
+   ``--python=python2.6`` options.
+
+The above provides an in-package install of ``virtualenv``. While this
+is counter to the conventional ``virtualenv`` configuration, it is
+more reliable and considerably easier to configure and illustrate. If
+you're familiar with Python packaging you may consider deploying with
+your preferred method.
+
+Assuming you are going to deploy with FastCGI, you should also install
+flup::
+
+    ./bin/easy_install flup
+
+(Sometimes this breaks because flup's site is flakey.  If it does for
+you, try)::
+
+    ./bin/easy_install https://pypi.python.org/pypi/flup/1.0.3.dev-20110405
+
+This concludes the initial configuration of the development
+environment. In the future, when you update your
+codebase, you should also run::
+
+    ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate
+
+Note: If you are running an active site, depending on your server
+configuration, you may need to stop it first or the dbupdate command
+may hang (and it's certainly a good idea to restart it after the
+update)
+
+
+Deploy MediaGoblin Services
+---------------------------
+
+Edit site configuration
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A few basic properties must be set before MediaGoblin will work. First
+make a copy of ``mediagoblin.ini`` for editing so the original config
+file isn't lost::
+
+    cp mediagoblin.ini mediagoblin_local.ini
+
+Then:
+ - Set ``email_sender_address`` to the address you wish to be used as
+   the sender for system-generated emails
+ - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if
+   your mediagoblin directory is not the root directory of your
+   vhost.
+
+
+Configure MediaGoblin to use the PostgreSQL database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are using postgres, edit the ``[mediagoblin]`` section in your
+``mediagoblin_local.ini`` and put in::
+
+    sql_engine = postgresql:///mediagoblin
+
+if you are running the MediaGoblin application as the same 'user' as the
+database owner.
+
+
+Update database data structures
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before you start using the database, you need to run::
+
+    ./bin/gmg dbupdate
+
+to populate the database with the MediaGoblin data structures.
+
+
+Test the Server
+~~~~~~~~~~~~~~~
+
+At this point MediaGoblin should be properly installed.  You can
+test the deployment with the following command::
+
+    ./lazyserver.sh --server-name=broadcast
+
+You should be able to connect to the machine on port 6543 in your
+browser to confirm that the service is operable.
+
+.. _webserver-config:
+
+
+FastCGI and nginx
+~~~~~~~~~~~~~~~~~
+
+This configuration example will use nginx, however, you may
+use any webserver of your choice as long as it supports the FastCGI
+protocol. If you do not already have a web server, consider nginx, as
+the configuration files may be more clear than the
+alternatives.
+
+Create a configuration file at
+``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link
+into a directory that will be included in your ``nginx`` configuration
+(e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with
+one of the following commands (as the root user)::
+
+    ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/
+    ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/
+
+Modify these commands and locations depending on your preferences and
+the existing configuration of your nginx instance. The contents of
+this ``nginx.conf`` file should be modeled on the following::
+
+    server {
+     #################################################
+     # Stock useful config options, but ignore them :)
+     #################################################
+     include /etc/nginx/mime.types;
+
+     autoindex off;
+     default_type  application/octet-stream;
+     sendfile on;
+
+     # Gzip
+     gzip on;
+     gzip_min_length 1024;
+     gzip_buffers 4 32k;
+     gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css;
+
+     #####################################
+     # Mounting MediaGoblin stuff
+     # This is the section you should read
+     #####################################
+
+     # Change this to update the upload size limit for your users
+     client_max_body_size 8m;
+
+     # prevent attacks (someone uploading a .txt file that the browser
+     # interprets as an HTML file, etc.)
+     add_header X-Content-Type-Options nosniff;
+
+     server_name mediagoblin.example.org www.mediagoblin.example.org;
+     access_log /var/log/nginx/mediagoblin.example.access.log;
+     error_log /var/log/nginx/mediagoblin.example.error.log;
+
+     # MediaGoblin's stock static files: CSS, JS, etc.
+     location /mgoblin_static/ {
+        alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/;
+     }
+
+     # Instance specific media:
+     location /mgoblin_media/ {
+        alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/;
+     }
+
+     # Theme static files (usually symlinked in)
+     location /theme_static/ {
+        alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/;
+     }
+
+     # Plugin static files (usually symlinked in)
+     location /plugin_static/ {
+        alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
+     }
+
+     # Mounting MediaGoblin itself via FastCGI.
+     location / {
+        fastcgi_pass 127.0.0.1:26543;
+        include /etc/nginx/fastcgi_params;
+
+        # our understanding vs nginx's handling of script_name vs
+        # path_info don't match :)
+        fastcgi_param PATH_INFO $fastcgi_script_name;
+        fastcgi_param SCRIPT_NAME "";
+     }
+    }
+
+Now, nginx instance is configured to serve the MediaGoblin
+application. Perform a quick test to ensure that this configuration
+works. Restart nginx so it picks up your changes, with a command that
+resembles one of the following (as the root user)::
+
+    sudo /etc/init.d/nginx restart
+    sudo /etc/rc.d/nginx restart
+
+Now start MediaGoblin. Use the following command sequence as an
+example::
+
+    cd /srv/mediagoblin.example.org/mediagoblin/
+    ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
+
+Visit the site you've set up in your browser by visiting
+<http://mediagoblin.example.org>. You should see MediaGoblin!
+
+.. note::
+
+   The configuration described above is sufficient for development and
+   smaller deployments. However, for larger production deployments
+   with larger processing requirements, see the
+   ":doc:`production-deployments`" documentation.
+   
+
+Apache
+~~~~~~
+
+Instructions and scripts for running MediaGoblin on an Apache server
+can be found on the `MediaGoblin wiki <http://wiki.mediagoblin.org/Deployment>`_.
+
+
+Security Considerations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+
+   The directory ``user_dev/crypto/`` contains some very
+   sensitive files.
+   Especially the ``itsdangeroussecret.bin`` is very important
+   for session security. Make sure not to leak its contents anywhere.
+   If the contents gets leaked nevertheless, delete your file
+   and restart the server, so that it creates a new secret key.
+   All previous sessions will be invalifated then.
diff --git a/docs/source/siteadmin/foreword.rst b/docs/source/siteadmin/foreword.rst
new file mode 100644
index 00000000..4c425f8d
--- /dev/null
+++ b/docs/source/siteadmin/foreword.rst
@@ -0,0 +1,48 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+========
+Foreword
+========
+
+About the Site Administrator's Guide
+====================================
+
+This is the site administrator manual for GNU MediaGoblin.  It covers
+how to set up and configure MediaGoblin and the kind of information
+that someone running MediaGoblin would need to know.
+
+We have other documentation at:
+
+* http://mediagoblin.org/join/ for general "join us" information
+* http://wiki.mediagoblin.org/ for our contributor/developer-focused wiki
+
+
+Improving the Site Administrator's Guide
+========================================
+
+There are a few ways---please pick whichever method is convenient for
+you!
+
+1. Write up a bug report in the bug tracker
+2. Tell someone on IRC ``#mediagoblin`` on Freenode.
+3. Write an email to the devel mailing list.
+
+Information about the bugtracker, IRC and the mailing list is all on
+the `join page`_.
+
+.. _join page: http://mediagoblin.org/join/
+
+Patches are the most helpful, but even feedback on what you think
+could be improved and how to improve it is also helpful.
+
diff --git a/docs/source/siteadmin/help.rst b/docs/source/siteadmin/help.rst
new file mode 100644
index 00000000..4b584ac1
--- /dev/null
+++ b/docs/source/siteadmin/help.rst
@@ -0,0 +1,29 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+==================================
+ How to Get Help with MediaGoblin
+==================================
+
+There are a couple of ways to get help with problems with MediaGoblin:
+
+1. ask for help on IRC
+
+2. ask for help on the devel mailing list
+
+Details for both IRC and the mailing list are on the `join page`_ of the
+website.
+
+.. _join page: http://mediagoblin.org/join/
+
+
diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst
new file mode 100644
index 00000000..1527bc70
--- /dev/null
+++ b/docs/source/siteadmin/media-types.rst
@@ -0,0 +1,245 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+.. _media-types-chapter:
+
+====================
+Media Types
+====================
+
+In the future, there will be all sorts of media types you can enable,
+but in the meanwhile there are three additional media types: video, audio
+and ascii art.
+
+First, you should probably read ":doc:`configuration`" to make sure
+you know how to modify the mediagoblin config file.
+
+
+Enabling Media Types
+====================
+
+Media types are enabled in your mediagoblin configuration file, typically it is
+created by copying ``mediagoblin.ini`` to ``mediagoblin_local.ini`` and then
+applying your changes to ``mediagoblin_local.ini``. If you don't already have a
+``mediagoblin_local.ini``, create one in the way described.
+
+Most media types have additional dependencies that you will have to install.
+You will find descriptions on how to satisfy the requirements of each media type
+on this page.
+
+To enable a media type, edit the ``media_types`` list in your
+``mediagoblin_local.ini``. For example, if your system supported image and
+video media types, then the list would look like this::
+
+    media_types = mediagoblin.media_types.image, mediagoblin.media_types.video
+
+Note that after enabling new media types, you must run dbupdate like so::
+
+    ./bin/gmg dbupdate
+
+If you are running an active site, depending on your server
+configuration, you may need to stop it first (and it's certainly a
+good idea to restart it after the update).
+
+
+How does MediaGoblin decide which media type to use for a file?
+===============================================================
+
+MediaGoblin has two methods for finding the right media type for an uploaded
+file. One is based on the file extension of the uploaded file; every media type
+maintains a list of supported file extensions. The second is based on a sniffing
+handler, where every media type may inspect the uploaded file and tell if it
+will accept it.
+
+The file-extension-based approach is used before the sniffing-based approach,
+if the file-extension-based approach finds a match, the sniffing-based approach
+will be skipped as it uses far more processing power.
+
+
+Video
+=====
+
+To enable video, first install gstreamer and the python-gstreamer
+bindings (as well as whatever gstremaer extensions you want,
+good/bad/ugly).  On Debianoid systems
+
+.. code-block:: bash
+
+    sudo apt-get install python-gst0.10 \
+        gstreamer0.10-plugins-base \
+        gstreamer0.10-plugins-bad \
+        gstreamer0.10-plugins-good \
+        gstreamer0.10-plugins-ugly \
+        gstreamer0.10-ffmpeg
+
+
+Add ``mediagoblin.media_types.video`` to the ``media_types`` list in your
+``mediagoblin_local.ini`` and restart MediaGoblin.
+
+Run
+
+.. code-block:: bash
+
+    ./bin/gmg dbupdate
+
+Now you should be able to submit videos, and mediagoblin should
+transcode them.
+
+.. note::
+
+   You almost certainly want to separate Celery from the normal
+   paste process or your users will probably find that their connections
+   time out as the video transcodes.  To set that up, check out the
+   ":doc:`production-deployments`" section of this manual.
+
+
+Audio
+=====
+
+To enable audio, install the gstreamer and python-gstreamer bindings (as well
+as whatever gstreamer plugins you want, good/bad/ugly), scipy and numpy are
+also needed for the audio spectrograms.
+To install these on Debianoid systems, run::
+
+    sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \
+        gstreamer0.10-ffmpeg python-numpy python-scipy
+
+The ``scikits.audiolab`` package you will install in the next step depends on the
+``libsndfile1-dev`` package, so we should install it.
+On Debianoid systems, run
+
+.. code-block:: bash
+
+    sudo apt-get install libsndfile1-dev
+
+.. note::
+    scikits.audiolab will display a warning every time it's imported if you do
+    not compile it with alsa support. Alsa support is not necessary for the GNU
+    MediaGoblin application but if you do not wish the alsa warnings from
+    audiolab you should also install ``libasound2-dev`` before installing
+    scikits.audiolab.
+
+Then install ``scikits.audiolab`` for the spectrograms::
+
+    ./bin/pip install scikits.audiolab
+
+Add ``mediagoblin.media_types.audio`` to the ``media_types`` list in your
+``mediagoblin_local.ini`` and restart MediaGoblin.
+
+Run
+
+.. code-block:: bash
+
+    ./bin/gmg dbupdate
+
+You should now be able to upload and listen to audio files!
+
+
+Ascii art
+=========
+
+To enable ascii art support, first install the
+`chardet <http://pypi.python.org/pypi/chardet>`_
+library, which is necessary for creating thumbnails of ascii art
+
+.. code-block:: bash
+
+    ./bin/easy_install chardet
+
+
+Next, modify (and possibly copy over from ``mediagoblin.ini``) your
+``mediagoblin_local.ini``.  In the ``[mediagoblin]`` section, add
+``mediagoblin.media_types.ascii`` to the ``media_types`` list.
+
+For example, if your system supported image and ascii art media types, then
+the list would look like this::
+
+    media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii
+
+Run
+
+.. code-block:: bash
+
+    ./bin/gmg dbupdate
+
+Now any .txt file you uploaded will be processed as ascii art!
+
+
+STL / 3d model support
+======================
+
+To enable the "STL" 3d model support plugin, first make sure you have
+a recentish `Blender <http://blender.org>`_ installed and available on
+your execution path.  This feature has been tested with Blender 2.63.
+It may work on some earlier versions, but that is not guaranteed (and
+is surely not to work prior to Blender 2.5X).
+
+Add ``mediagoblin.media_types.stl`` to the ``media_types`` list in your
+``mediagoblin_local.ini`` and restart MediaGoblin. 
+
+Run
+
+.. code-block:: bash
+
+    ./bin/gmg dbupdate
+
+You should now be able to upload .obj and .stl files and MediaGoblin
+will be able to present them to your wide audience of admirers!
+
+PDF and Document
+================
+
+To enable the "PDF and Document" support plugin, you need:
+
+1. pdftocairo and pdfinfo for pdf only support.
+
+2. unoconv with headless support to support converting libreoffice supported
+   documents as well, such as doc/ppt/xls/odf/odg/odp and more.
+   For the full list see mediagoblin/media_types/pdf/processing.py,
+   unoconv_supported.
+
+All executables must be on your execution path.
+
+To install this on Fedora:
+
+.. code-block:: bash
+
+    sudo yum install -y poppler-utils unoconv libreoffice-headless
+
+Note: You can leave out unoconv and libreoffice-headless if you want only pdf
+support. This will result in a much smaller list of dependencies.
+
+pdf.js relies on git submodules, so be sure you have fetched them:
+
+.. code-block:: bash
+
+    git submodule init
+    git submodule update
+
+This feature has been tested on Fedora with:
+ poppler-utils-0.20.2-9.fc18.x86_64
+ unoconv-0.5-2.fc18.noarch
+ libreoffice-headless-3.6.5.2-8.fc18.x86_64
+
+It may work on some earlier versions, but that is not guaranteed.
+
+Add ``mediagoblin.media_types.pdf`` to the ``media_types`` list in your
+``mediagoblin_local.ini`` and restart MediaGoblin. 
+
+Run
+
+.. code-block:: bash
+
+    ./bin/gmg dbupdate
+
+
diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst
new file mode 100644
index 00000000..baca381d
--- /dev/null
+++ b/docs/source/siteadmin/plugins.rst
@@ -0,0 +1,177 @@
+=========
+ Plugins
+=========
+
+GNU MediaGoblin supports plugins that allow you to augment MediaGoblin's
+behavior.
+
+This chapter covers discovering, installing, configuring and removing
+plugins.
+
+
+Discovering plugins
+===================
+
+MediaGoblin comes with core plugins. Core plugins are located in the
+``mediagoblin.plugins`` module of the MediaGoblin code. Because they
+come with MediaGoblin, you don't have to install them, but you do have
+to add them to your config file if you're interested in using them.
+
+You can also write your own plugins and additionally find plugins
+elsewhere on the Internet. Once you find a plugin you like, you need
+to first install it, then add it to your configuration.
+
+.. todo: how do you find plugins on the internet?
+
+
+Installing plugins
+==================
+
+Core plugins
+------------
+
+MediaGoblin core plugins don't need to be installed because they come
+with MediaGoblin. Further, when you upgrade MediaGoblin, you will also
+get updates to the core plugins.
+
+
+Other plugins
+-------------
+
+If the plugin is available on the `Python Package Index
+<http://pypi.python.org/pypi>`_, then you can install the plugin with pip::
+
+    pip install <plugin-name>
+
+For example, if we wanted to install the plugin named
+"mediagoblin-licenses" (which allows you to customize the licenses you
+offer for your media), we would do::
+
+    pip install mediagoblin-licenses
+
+.. Note::
+
+   If you're using a virtual environment, make sure to activate the
+   virtual environment before installing with pip. Otherwise the plugin
+   may get installed in a different environment than the one MediaGoblin
+   is installed in. Also make sure, you use e.g. pip-2.7 if your default
+   python (and thus pip) is python 3 (e.g. in Ubuntu).
+
+Once you've installed the plugin software, you need to tell
+MediaGoblin that this is a plugin you want MediaGoblin to use. To do
+that, you edit the ``mediagoblin.ini`` file and add the plugin as a
+subsection of the plugin section.
+
+For example, say the "mediagoblin-licenses" plugin has the Python
+package path ``mediagoblin_licenses``, then you would add ``mediagoblin_licenses`` to
+the ``plugins`` section as a subsection::
+
+    [plugins]
+
+    [[mediagoblin_licenses]]
+    license_01=abbrev1, name1, http://url1
+    license_02=abbrev2, name1, http://url2
+
+
+Configuring plugins
+===================
+
+Configuration for a plugin goes in the subsection for that plugin. Core
+plugins are documented in the administration guide. Other plugins
+should come with documentation that tells you how to configure them.
+
+Example 1: Core MediaGoblin plugin
+
+If you wanted to use the core MediaGoblin flatpages plugin, the module
+for that is ``mediagoblin.plugins.flatpagesfile`` and you would add
+that to your ``.ini`` file like this::
+
+    [plugins]
+
+    [[mediagoblin.plugins.flatpagesfile]]
+    # configuration for flatpagesfile plugin here!
+    about-view = '/about', about.html
+    terms-view = '/terms', terms.html
+
+(Want to know more about the flatpagesfile plugin?  See
+:ref:`flatpagesfile-chapter`)
+
+Example 2: Plugin that is not a core MediaGoblin plugin
+
+If you installed a hypothetical restrictfive plugin which is in the
+module ``restrictfive``, your ``.ini`` file might look like this (with
+comments making the bits clearer)::
+
+    [plugins]
+
+    [[restrictfive]]
+    # configuration for restrictfive here!
+
+Check the plugin's documentation for what configuration options are
+available.
+
+
+Removing plugins
+================
+
+To remove a plugin, use ``pip uninstall``. For example::
+
+    pip uninstall mediagoblin-licenses
+
+.. Note::
+
+   If you're using a virtual environment, make sure to activate the
+   virtual environment before uninstalling with pip. Otherwise the
+   plugin may get installed in a different environment.
+
+
+Upgrading plugins
+=================
+
+Core plugins
+------------
+
+Core plugins get upgraded automatically when you upgrade MediaGoblin
+because they come with MediaGoblin.
+
+
+Other plugins
+-------------
+
+For plugins that you install with pip, you can upgrade them with pip::
+
+    pip install -U <plugin-name>
+
+The ``-U`` tells pip to upgrade the package.
+
+
+Troubleshooting plugins
+=======================
+
+Sometimes plugins just don't work right. When you're having problems
+with plugins, think about the following:
+
+1. Check the log files.
+
+   Some plugins will log errors to the log files and you can use that
+   to diagnose the problem.
+
+2. Try running MediaGoblin without that plugin.
+
+   It's easy to disable a plugin from MediaGoblin. Add a ``-`` to the
+   name in your config file.
+
+   For example, change::
+
+       [[mediagoblin.plugins.flatpagesfile]]
+
+   to::
+
+       [[-mediagoblin.plugins.flatpagesfile]]
+
+   That'll prevent the ``mediagoblin.plugins.flatpagesfile`` plugin from
+   loading.
+
+3. If it's a core plugin that comes with MediaGoblin, ask us for help!
+
+   If it's a plugin you got from somewhere else, ask them for help!
diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst
new file mode 100644
index 00000000..839d3ce5
--- /dev/null
+++ b/docs/source/siteadmin/production-deployments.rst
@@ -0,0 +1,133 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+=========================================
+Considerations for Production Deployments
+=========================================
+
+This document contains a number of suggestions for deploying
+MediaGoblin in actual production environments. Consider
+":doc:`deploying`" for a basic overview of how to deploy MediaGoblin.
+
+Deploy with Paste
+-----------------
+
+The MediaGoblin WSGI application instance you get with ``./lazyserver.sh`` is
+not ideal for a production MediaGoblin deployment. Ideally, you should be able
+to use an "init" or "control" script to launch and restart the MediaGoblin
+process.
+
+Use the following command as the basis for such a script:
+
+.. code-block:: bash
+
+    CELERY_ALWAYS_EAGER=true \
+     /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
+     /srv/mediagoblin.example.org/mediagoblin/paste.ini \
+     --pid-file=/var/run/mediagoblin.pid \
+     --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
+
+The above configuration places MediaGoblin in "always eager" mode
+with Celery, this means that submissions of content will be processed
+synchronously, and the user will advance to the next page only after
+processing is complete. If we take Celery out of "always eager mode,"
+the user will be able to immediately return to the MediaGoblin site
+while processing is ongoing. In these cases, use the following command
+as the basis for your script:
+
+.. code-block:: bash
+
+    CELERY_ALWAYS_EAGER=false \
+     /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \
+     /srv/mediagoblin.example.org/mediagoblin/paste.ini \
+     --pid-file=/var/run/mediagoblin.pid \
+     --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543
+
+Separate Celery
+---------------
+
+MediaGoblin uses `Celery`_ to handle heavy and long-running tasks. Celery can
+be launched in two ways:
+
+1.  Embedded in the MediaGoblin WSGI application [#f-mediagoblin-wsgi-app]_.
+    This is the way ``./lazyserver.sh`` does it for you. It's simple as you
+    only have to run one process. The only bad thing with this is that the
+    heavy and long-running tasks will run *in* the webserver, keeping the user
+    waiting each time some heavy lifting is needed as in for example processing
+    a video. This could lead to problems as an aborted connection will halt any
+    processing and since most front-end web servers *will* terminate your
+    connection if it doesn't get any response from the MediaGoblin WSGI
+    application in a while.
+
+2.  As a separate process communicating with the MediaGoblin WSGI application
+    via a `broker`_. This offloads the heavy lifting from the MediaGoblin WSGI
+    application and users will be able to continue to browse the site while the
+    media is being processed in the background.
+
+.. _`broker`: http://docs.celeryproject.org/en/latest/getting-started/brokers/
+.. _`celery`: http://www.celeryproject.org/
+
+
+.. [#f-mediagoblin-wsgi-app] The MediaGoblin WSGI application is the part that
+    of MediaGoblin that processes HTTP requests.
+
+To launch Celery separately from the MediaGoblin WSGI application:
+
+1.  Make sure that the ``CELERY_ALWAYS_EAGER`` environment variable is unset or
+    set to ``false`` when launching the MediaGoblin WSGI application.
+2.  Start the ``celeryd`` main process with
+
+    .. code-block:: bash
+
+        CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
+
+.. _sentry:
+
+Set up sentry to monitor exceptions
+-----------------------------------
+
+We have a plugin for `raven`_ integration, see the ":doc:`/plugindocs/raven`"
+documentation.
+
+.. _`raven`: http://raven.readthedocs.org
+
+
+.. _init-script:
+
+Use an Init Script
+------------------
+
+Look in your system's ``/etc/init.d/`` or ``/etc/rc.d/`` directory for
+examples of how to build scripts that will start, stop, and restart
+MediaGoblin and Celery. These scripts will vary by
+distribution/operating system.
+
+These are scripts provided by the MediaGoblin community: 
+
+Debian
+  * `GNU MediaGoblin init scripts
+    <https://github.com/joar/mediagoblin-init-scripts>`_
+    by `Joar Wandborg <http://wandborg.se>`_
+
+Arch Linux
+  * `MediaGoblin - ArchLinux rc.d scripts
+    <http://whird.jpope.org/2012/04/14/mediagoblin-archlinux-rcd-scripts>`_
+    by `Jeremy Pope <http://jpope.org/>`_
+  * `Mediagoblin init script on Archlinux
+    <http://chimo.chromic.org/2012/03/01/mediagoblin-init-script-on-archlinux/>`_
+    by `Chimo <http://chimo.chromic.org/>`_
+
+.. TODO insert init script here
+.. TODO are additional concerns ?
+   .. Other Concerns
+   .. --------------
diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst
new file mode 100644
index 00000000..7b6d8353
--- /dev/null
+++ b/docs/source/siteadmin/relnotes.rst
@@ -0,0 +1,300 @@
+.. MediaGoblin Documentation
+
+   Written in 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+.. _release-notes:
+
+=============
+Release Notes
+=============
+
+This chapter has important information for releases in it.
+If you're upgrading from a previous release, please read it
+carefully, or at least skim over it.
+
+0.4.0
+=====
+
+**Do this to upgrade**
+1. Make sure to run ``bin/gmg dbupdate`` after upgrading.
+2. See "For Theme authors" if you have a custom theme.
+3. Note that ``./bin/gmg theme assetlink`` is now just
+   ``./bin/gmg assetlink`` and covers both plugins and assets.
+   Keep on reading to hear more about new plugin features.
+4. If you want to take advantage of new plugins that have statically
+   served assets, you are going to need to add the new "plugin_static"
+   section to your nginx config.  Basically the following for nginx::
+
+     # Plugin static files (usually symlinked in)
+     location /plugin_static/ {
+        alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
+     }
+
+   Similarly, if you've got a modified paste config, you may want to
+   borrow the app:plugin_static section from the default paste.ini
+   file.
+5. We now use itsdangerous for sessions; if you had any references to
+   beaker in your paste config you can remove them.  Again, see the
+   default paste.ini config
+
+**For theme authors**
+
+If you have your own theme or you have any "user modified templates",
+please note the following:
+
+* mediagoblin/bits/ files above-content.html, body-end.html,
+  body-start.html now are renamed... they have underscores instead of
+  dashes in the filenames now :)
+* There's a new file: ``mediagoblin/bits/frontpage_welcome.html``.
+  You can easily customize this to give a welcome page appropriate to
+  your site.
+
+
+**New features**
+* PDF media type!
+* Improved plugin system.  More flexible, better documented, with a
+  new plugin authoring section of the docs.
+* itsdangerous based sessions.  No more beaker!
+* New, experimental Piwigo-based API.  This means you should be able
+  to use MediaGoblin with something like Shotwell.  (Again, a word of
+  caution: this is *very experimental*!)
+* Human readable timestamps, and the option to display the original
+  date of an image when available (available as the
+  "original_date_visible" variable)
+* Moved unit testing system from nosetests to py.test so we can better
+  handle issues with sqlalchemy exploding with different database
+  configurations.  Long story :)
+* You can now disable the ability to post comments.
+* Tags now can be up to length 255 characters by default.
+
+
+0.3.3
+=====
+
+**Do this to upgrade**
+
+1. Make sure to run ``bin/gmg dbupdate`` after upgrading.
+2. OpenStreetMap is now a plugin, so if you want to use it, add the
+   following to your config file:
+
+   .. code-block:: ini
+
+      [plugins]
+      [[mediagoblin.plugins.geolocation]]
+
+If you have your own theme, you may need to make some adjustments to
+it as some theme related things may have changed in this release.  If
+you run into problems, don't hesitate to
+`contact us <http://mediagoblin.org/pages/join.html>`_
+(IRC is often best).
+
+**New features**
+
+* New dropdown menu for accessing various features.
+
+* Significantly improved URL generation.  Now mediagoblin won't give
+  up on making a slug if it looks like there will be a duplicate;
+  it'll try extra hard to generate a meaningful one instead.
+
+  Similarly, linking to an id no longer can possibly conflict with
+  linking to a slug; /u/username/m/id:35/ is the kind of reference we
+  now use to linking to entries with ids.  However, old links with
+  entries that linked to ids should work just fine with our migration.
+  The only urls that might break in this release are ones using colons
+  or equal signs.
+
+* New template hooks for plugin authoring.
+
+* As a demonstration of new template hooks for plugin authoring,
+  openstreetmap support now moved to a plugin!
+
+* Method to add media to collections switched from icon of paperclip
+  to button with "add to collection" text.
+
+* Bug where videos often failed to produce a proper thumbnail fixed!
+
+* Copying around files in MediaGoblin now much more efficient, doesn't
+  waste gobs of memory.
+
+* Video transcoding now optional for videos that meet certain
+  criteria.  By default, MediaGoblin will not transcode webm videos
+  that are smaller in resolution than the MediaGoblin defaults, and
+  MediaGoblin can also be configured to allow theora files to not be
+  transcoded as well.
+
+* Per-user license preference option; always want your uploads to be
+  BY-SA and tired of changing that field?  You can now set your
+  license preference in your user settings.
+
+* Video player now responsive; better for mobile!
+
+* You can now delete your account from the user preferences page if
+  you so wish.
+
+**Other changes**
+
+* Plugin writers: Internal restructuring led to mediagoblin.db.sql* be
+  mediagoblin.db.* starting from 0.3.3
+
+* Dependency list has been reduced not requiring the "webob" package anymore.
+
+* And many small fixes/improvements, too numerous to list!
+
+
+0.3.2
+=====
+
+This will be the last release that is capable of converting from an earlier
+MongoDB-based MediaGoblin instance to the newer SQL-based system.
+
+**Do this to upgrade**
+
+    # directory of your mediagoblin install
+    cd /srv/mediagoblin.example.org
+
+    # copy source for this release
+    git fetch
+    git checkout tags/v0.3.2
+
+    # perform any needed database updates
+    bin/gmg dbupdate
+    
+    # restart your servers however you do that, e.g.,
+    sudo service mediagoblin-paster restart
+    sudo service mediagoblin-celeryd restart
+
+
+**New features**
+
+* **3d model support!**
+
+  You can now upload STL and OBJ files and display them in
+  MediaGoblin.  Requires a recent-ish Blender; for details see:
+  :ref:`deploying-chapter`
+
+* **trim_whitespace**
+
+  We bundle the optional plugin trim_whitespace which reduces the size
+  of the delivered html output by reducing redundant whitespace.
+
+  See :ref:`core-plugin-section` for plugin documentation
+
+* **A new API!**
+
+  It isn't well documented yet but we do have an API.  There is an
+  `android application in progress <https://gitorious.org/mediagoblin/mediagoblin-android>`_
+  which makes use of it, and there are some demo applications between
+  `automgtic <https://github.com/jwandborg/automgtic>`_, an
+  automatic media uploader for your desktop
+  and `OMGMG <https://github.com/jwandborg/omgmg>`_, an example of
+  a web application hooking up to the API.
+
+  This is a plugin, so you have to enable it in your mediagoblin
+  config file by adding a section under [plugins] like::
+
+    [plugins]
+    [[mediagoblin.plugins.api]]
+
+  Note that the API works but is not nailed down... the way it is
+  called may change in future releases.
+
+* **OAuth login support**
+
+  For applications that use OAuth to connect to the API.
+
+  This is a plugin, so you have to enable it in your mediagoblin
+  config file by adding a section under [plugins] like::
+
+    [plugins]
+    [[mediagoblin.plugins.oauth]]
+
+* **Collections**
+
+  We now have user-curated collections support.  These are arbitrary
+  galleries that are customizable by users.  You can add media to
+  these by clicking on the paperclip icon when logged in and looking
+  at a media entry.
+
+* **OpenStreetMap licensing display improvements**
+
+  More accurate display of OSM licensing, and less disruptive: you
+  click to "expand" the display of said licensing.
+
+  Geolocation is also now on by default.
+
+* **Miscelaneous visual improvements**
+
+  We've made a number of small visual improvements including newer and
+  nicer looking thumbnails and improved checkbox placement.
+
+
+
+0.3.1
+=====
+
+**Do this to upgrade**
+
+1. Make sure to run ``bin/gmg dbuptdate`` after upgrading.
+
+2. If you set up your server config with an older version of
+   mediagoblin and the mediagoblin docs, it's possible you don't
+   have the "theme static files" alias, so double check to make
+   sure that section is there if you are having problems.
+
+
+
+**New features**
+
+* **theming support**
+
+  MediaGoblin now also includes theming support, which you can
+  read about in the section :ref:`theming-chapter`.
+
+* **flatpages**
+
+  MediaGoblin has a flatpages plugin allowing you to add pages that
+  are aren't media-related like "About this site...", "Terms of
+  service...", etc.
+
+  See :ref:`core-plugin-section` for plugin documentation
+
+
+0.3.0
+=====
+
+This release has one important change. You need to act when
+upgrading from a previous version!
+
+This release changes the database system from MongoDB to
+SQL(alchemy). If you want to setup a fresh instance, just
+follow the instructions in the deployment chapter. If on
+the other hand you want to continue to use one instance,
+read on.
+
+To convert your data from MongoDB to SQL(alchemy), you need
+to follow these steps:
+
+1. Make sure your MongoDB is still running and has your
+   data, it's needed for the conversion.
+
+2. Configure the ``sql_engine`` URI in the config to represent
+   your target database (see: :ref:`deploying-chapter`)
+
+3. You need an empty database.
+
+4. Then run the following command::
+
+       bin/gmg [-cf mediagoblin_config.ini] convert_mongo_to_sql
+
+5. Start your server and investigate.
+
+6. That's it.
diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst
new file mode 100644
index 00000000..11ae3875
--- /dev/null
+++ b/docs/source/siteadmin/theming.rst
@@ -0,0 +1,281 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+.. _theming-chapter:
+
+=====================
+ Theming MediaGoblin
+=====================
+
+We try to provide a nice theme for MediaGoblin by default, but of
+course, you might want something different!  Maybe you want something
+more light and colorful, or maybe you want something specifically
+tailored to your organization.  Have no fear---MediaGoblin has theming
+support!  This guide should walk you through installing and making
+themes.
+
+
+Installing a theme
+==================
+
+.. _theming-installing-section:
+
+Installing the archive
+----------------------
+
+Say you have a theme archive such as ``goblincities.tar.gz`` and you
+want to install this theme!  Don't worry, it's fairly painless.
+
+1. ``cd ./user_dev/themes/``
+
+2. Move the theme archive into this directory
+
+3. ``tar -xzvf <tar-archive>``
+
+4. Open your configuration file (probably named
+   ``mediagoblin_local.ini``) and set the theme name::
+
+       [mediagoblin]
+       # ...
+       theme = goblincities
+
+5. Link the assets so that they can be served by your web server::
+
+       $ ./bin/gmg assetlink
+
+.. Note::
+
+   If you ever change the current theme in your config file, you
+   should re-run the above command!
+
+(In the near future this should be even easier ;))
+
+.. In the future, this might look more like:
+.. Installing a theme in MediaGoblin is fairly easy!  Assuming you
+.. already have a theme package, just do this::
+..
+..     $ ./bin/gmg theme install --fullsetup goblincities.tar.gz
+..
+.. This would install the theme, set it as current, and symlink its
+.. assets.
+
+
+Set up your webserver to serve theme assets
+-------------------------------------------
+
+If you followed the nginx setup example in :ref:`webserver-config` you
+should already have theme asset setup.  However, if you set up your
+server config with an older version of mediagoblin and the mediagoblin
+docs, it's possible you don't have the "theme static files" alias, so
+double check to make sure that section is there if you are having
+problems.
+
+If you are simply using this for local development and serving the
+whole thing via paste/lazyserver, assuming you don't have a
+paste_local.ini, the asset serving should be done for you.
+
+
+Configuring where things go
+---------------------------
+
+By default, MediaGoblin's install directory for themes is
+``./user_dev/themes/`` (relative to the MediaGoblin checkout or base
+config file.)  However, you can change this location easily with the
+``theme_install_dir`` setting in the ``[mediagoblin]`` section.
+
+For example::
+
+    [mediagoblin]
+    # ... other parameters go here ...
+    theme_install_dir = /path/to/themes/
+
+Other variables you may consider setting:
+
+`theme_web_path`
+    When theme-specific assets are specified, this is where MediaGoblin
+    will set the urls.  By default this is ``"/theme_static/"`` so in
+    the case that your theme was trying to access its file 
+    ``"images/shiny_button.png"`` MediaGoblin would link
+    to ``/theme_static/images/shiny_button.png``.
+
+`theme_linked_assets_dir`
+    Your web server needs to serve the theme files out of some directory,
+    and MediaGoblin will symlink the current theme's assets here.  See
+    the "Link the assets" step in :ref:`theming-installing-section`.
+
+
+Making a theme
+==============
+
+Okay, so a theme layout is pretty simple.  Let's assume we're making a
+theme for an instance about hedgehogs!  We'll call this the
+"hedgehogified" theme.
+
+Change to where your ``theme_install_dir`` is set to (by default,
+``./user_dev/themes/`` ... make those directories or otherwise adjust
+if necessary)::
+
+    hedgehogified/
+    |- theme.cfg                # configuration file for this theme
+    |- templates/               # override templates
+    |  '- mediagoblin/
+    |     |- base.html          # overriding mediagoblin/base.html
+    |     '- root.html          # overriding mediagoblin/root.html
+    '- assets/
+    |  '- images/
+    |  |  |- im_a_hedgehog.png  # hedgehog-containing image used by theme
+    |  |  '- custom_logo.png    # your theme's custom logo
+    |  '- css/
+    |     '- hedgehog.css       # your site's hedgehog-specific css
+    |- README.txt               # Optionally, a readme file (not required)
+    |- AGPLv3.txt               # AGPL license file for your theme. (good practice)
+    '- CC0_1.0.txt              # CC0 1.0 legalcode for the assets [if appropriate!]
+
+
+The top level directory of your theme should be the symbolic name for
+your theme.  This is the name that users will use to refer to activate
+your theme.
+
+.. Note::
+
+   It's important to note that templates based on MediaGoblin's code
+   should be released as AGPLv3 (or later), like MediaGoblin's code
+   itself.  However, all the rest of your assets are up to you.  In this
+   case, we are waiving our copyright for images and CSS into the public
+   domain via CC0 (as MediaGoblin does) but do what's appropriate to you.
+
+
+The config file
+===============
+
+The config file is not presently strictly required, though it is nice to have.
+Only a few things need to go in here::
+
+    [theme]
+    name = Hedgehog-ification
+    description = For hedgehog lovers ONLY
+    licensing = AGPLv3 or later templates; assets (images/css) waived under CC0 1.0
+
+The name and description fields here are to give users an idea of what
+your theme is about.  For the moment, we don't have any listing
+directories or admin interface, so this probably isn't useful, but
+feel free to set it in anticipation of a more glorious future.
+
+Licensing field is likewise a textual description of the stuff here;
+it's recommended that you preserve the "AGPLv3 or later templates" and
+specify whatever is appropriate to your assets.
+
+
+Templates
+---------
+
+Your template directory is where you can put any override and custom
+templates for MediaGoblin.
+
+These follow the general MediaGoblin theming layout, which means that
+the MediaGoblin core templates are all kept under the ``./mediagoblin/``
+prefix directory.
+
+You can copy files right out of MediaGoblin core and modify them in
+this matter if you wish.
+
+To fit with best licensing form, you should either preserve the
+MediaGoblin copyright header borrowing from a MediaGoblin template, or
+you may include one like the following::
+
+    {#
+    # [YOUR THEME], a MediaGoblin theme
+    # Copyright (C) [YEAR] [YOUR NAME]
+    #
+    # This program is free software: you can redistribute it and/or modify
+    # it under the terms of the GNU Affero General Public License as published by
+    # the Free Software Foundation, either version 3 of the License, or
+    # (at your option) any later version.
+    #
+    # This program is distributed in the hope that it will be useful,
+    # but WITHOUT ANY WARRANTY; without even the implied warranty of
+    # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    # GNU Affero General Public License for more details.
+    #
+    # You should have received a copy of the GNU Affero General Public License
+    # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+    #}
+
+
+Assets
+------
+
+Put any files, such as images, CSS, etc, that are specific to your
+theme in here.
+
+You can reference these in your templates like so::
+
+    <img src="{{ request.staticdirect('/images/im_a_shark.png', 'theme') }}" />
+
+This will tell MediaGoblin to reference this image from the current theme.
+
+
+Licensing file(s)
+-----------------
+
+You should include AGPLv3.txt with your theme as this is required for
+the assets.  You can copy this from ``mediagoblin/licenses/``.
+
+In the above example, we also use CC0 to waive our copyrights to
+images and css, so we also included CC0_1.0.txt
+
+
+A README.txt file
+-----------------
+
+A README file is not strictly required, but probably a good idea.  You
+can put whatever in here, but restating the license choice clearly is
+probably a good idea.
+
+
+Simple theming by adding CSS
+----------------------------
+
+Many themes won't require anything other than the ability to override
+some of MediaGoblin's core css.  Thankfully, doing so is easy if you
+combine the above steps!
+
+In your theme, do the following (make sure you make the necessary
+directories and cd to your theme's directory first)::
+
+    $ cp /path/to/mediagoblin/mediagoblin/templates/mediagoblin/extra_head.html templates/mediagoblin/
+
+Great, now open that file and add something like this at the end::
+
+    <link rel="stylesheet" type="text/css"
+          href="{{ request.staticdirect('/css/theme.css', 'theme') }}"/>
+
+You can name the css file whatever you like.  Now make the directory
+for ``assets/css/`` and add the file ``assets/css/theme.css``.
+
+You can now put custom CSS files in here and any CSS you add will
+override default MediaGoblin CSS.
+
+
+Packaging it up!
+----------------
+
+Packaging a theme is really easy.  It's just a matter of making an archive!
+
+Change to the installed themes directory and run the following::
+
+    tar -cvfz yourtheme.tar.gz yourtheme
+
+Where "yourtheme" is replaced with your theme name.
+
+That's it!
diff --git a/docs/source/themes/mg/layout.html b/docs/source/themes/mg/layout.html
new file mode 100644
index 00000000..891ed64c
--- /dev/null
+++ b/docs/source/themes/mg/layout.html
@@ -0,0 +1,29 @@
+{#
+    default/layout.html
+    ~~~~~~~~~~~~~~~~~~~
+
+    Sphinx layout template for the default theme.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+#}
+{% extends "basic/layout.html" %}
+
+{% if theme_collapsiblesidebar|tobool %}
+{% set script_files = script_files + ['_static/sidebar.js'] %}
+{% endif %}
+
+{%- block footer %}
+    <div class="footer">
+    <div>
+
+MediaGoblin documentation released into the public domain via <a href="http://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.
+
+    {%- if last_updated %}
+      {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
+    {%- endif %}
+
+    {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}
+    </div>
+    </div>
+{%- endblock %}
diff --git a/docs/source/themes/mg/static/fonts/Lato-Bold.ttf b/docs/source/themes/mg/static/fonts/Lato-Bold.ttf
new file mode 120000
index 00000000..4e08d84d
--- /dev/null
+++ b/docs/source/themes/mg/static/fonts/Lato-Bold.ttf
@@ -0,0 +1 @@
+../../../../../../extlib/lato/Lato-Bold.ttf
\ No newline at end of file
diff --git a/docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf b/docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf
new file mode 120000
index 00000000..0b99eef8
--- /dev/null
+++ b/docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf
@@ -0,0 +1 @@
+../../../../../../extlib/lato/Lato-BoldItalic.ttf
\ No newline at end of file
diff --git a/docs/source/themes/mg/static/fonts/Lato-Italic.ttf b/docs/source/themes/mg/static/fonts/Lato-Italic.ttf
new file mode 120000
index 00000000..2dccfc82
--- /dev/null
+++ b/docs/source/themes/mg/static/fonts/Lato-Italic.ttf
@@ -0,0 +1 @@
+../../../../../../extlib/lato/Lato-Italic.ttf
\ No newline at end of file
diff --git a/docs/source/themes/mg/static/fonts/Lato-Regular.ttf b/docs/source/themes/mg/static/fonts/Lato-Regular.ttf
new file mode 120000
index 00000000..7b1bb468
--- /dev/null
+++ b/docs/source/themes/mg/static/fonts/Lato-Regular.ttf
@@ -0,0 +1 @@
+../../../../../../extlib/lato/Lato-Regular.ttf
\ No newline at end of file
diff --git a/docs/source/themes/mg/static/fonts/OFL_1.1.txt b/docs/source/themes/mg/static/fonts/OFL_1.1.txt
new file mode 120000
index 00000000..e71d0721
--- /dev/null
+++ b/docs/source/themes/mg/static/fonts/OFL_1.1.txt
@@ -0,0 +1 @@
+../../../../../../extlib/lato/OFL_1.1.txt
\ No newline at end of file
diff --git a/docs/source/themes/mg/static/logo_docs.png b/docs/source/themes/mg/static/logo_docs.png
new file mode 100644
index 00000000..99f04cc7
--- /dev/null
+++ b/docs/source/themes/mg/static/logo_docs.png
diff --git a/docs/source/themes/mg/static/mg.css b/docs/source/themes/mg/static/mg.css
new file mode 100644
index 00000000..96344df4
--- /dev/null
+++ b/docs/source/themes/mg/static/mg.css
@@ -0,0 +1,161 @@
+/*
+
+MediaGoblin theme - MediaGoblin-style Sphinx documentation theme
+
+Written in 2012 by Jef van Schendel <mail@jefvanschendel.nl>
+
+To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty. 
+
+You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>. 
+
+*/
+
+@import url("basic.css");
+
+/* text fonts and styles */
+
+@font-face {
+  font-family: 'Lato';
+  font-style: normal;
+  font-weight: 700;
+  src: local('Lato Bold'), local('Lato-Bold'), url('fonts/Lato-Bold.ttf') format('truetype');
+}
+@font-face {
+  font-family: 'Lato';
+  font-style: italic;
+  font-weight: 400;
+  src: local('Lato Italic'), local('Lato-Italic'), url('fonts/Lato-Italic.ttf') format('truetype');
+}
+@font-face {
+  font-family: 'Lato';
+  font-style: italic;
+  font-weight: 700;
+  src: local('Lato Bold Italic'), local('Lato-BoldItalic'), url('fonts/Lato-BoldItalic.ttf') format('truetype');
+}
+@font-face {
+  font-family: 'Lato';
+  font-style: normal;
+  font-weight: 400;
+  src: local('Lato Regular'), local('Lato-Regular'), url('fonts/Lato-Regular.ttf') format('truetype');
+}
+
+body {
+  font: 16px 'Lato',Helvetica,Arial,sans-serif;
+  background-color: #FCFCFC;
+  color: #3C3C3C;
+  margin: 0;
+  padding: 0;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  border-bottom: 1px solid #CCCCCC;
+  background: none;
+  color: black;
+  font-weight: bold;
+  padding-bottom: 0.17em;
+  padding-top: 0.5em;
+}
+
+h1 {
+  font-size: 1.875em;
+}
+
+h2 {
+  font-size: 1.375em;
+}
+
+h3, h4, h5, h6 {
+  font-size: 1.125em;
+}
+
+p {
+  font-weight: normal;
+  margin: 0.4em 0 0.5em;
+}
+
+a {
+  color: #499776;
+}
+
+a:visited {
+  color: #2A5744;
+}
+
+a:active {
+  color: #65D1A3;
+}
+
+h1 a, h2 a, h3 a, h4 a, h5 a, h6 a {
+  text-decoration: none;
+}
+
+div.topic, pre {
+  background-color: #F1F1F1;
+  border: 1px dashed #ccc;
+  color: black;
+  line-height: 1.1em;
+  padding: 1em;
+}
+
+code, tt {
+  font: 14px monospace,"Courier New";
+  background-color: #FFFFDD;
+  border: thin solid #bbb;
+  padding-left: 5px;
+  padding-right: 5px;
+}
+
+pre {
+  font: 14px monospace,"Courier New";
+}
+
+div.related a, div.related a:visited, div.related a:active {
+  color: #86D4B1;
+}
+
+/* layout */
+
+div.documentwrapper {
+    float: left;
+    width: 100%;
+}
+
+div.bodywrapper {
+    margin: 0 0 0 270px;
+}
+
+div.body {
+    padding: 0 20px 30px 20px;
+}
+
+div.footer {
+    width: 100%;
+    padding: 9px 0 9px 0;
+    text-align: center;
+    font-size: 75%;
+}
+
+div.sphinxsidebar {
+  width: 240px;
+}
+
+div.sphinxsidebarwrapper {
+  padding: 10px 5px 0 30px;
+}
+
+div.sphinxsidebar ul {
+    margin: 10px 10px 10px 0;
+    padding: 0;
+}
+
+div.related {
+  line-height: 30px;
+  font-size: 90%;
+  width: 100%;
+  background-color: #161616;
+  color: #C3C3C3;
+}
+
+p.logo {
+  margin-top: 30px;
+}
diff --git a/docs/source/themes/mg/theme.conf b/docs/source/themes/mg/theme.conf
new file mode 100644
index 00000000..dd58038a
--- /dev/null
+++ b/docs/source/themes/mg/theme.conf
@@ -0,0 +1,5 @@
+[theme]
+inherit = basic
+stylesheet = mg.css
+pygments_style = sphinx
+