Split docs into siteadmin and pluginwriter guides

* create initial bits for plugin writer's guide
* move siteadmin stuff to site administrator's guide
* rework index.rst to support multiple guides
* tweak some text
* move files into subdirectories

I verified that this still works with html and texinfo build targets.
There's still a lot of work to do, but this is a good start.

11 files changed, 1167 insertions, 0 deletions

diff --git a/docs/source/siteadmin/about.rst b/docs/source/siteadmin/about.rst
new file mode 100644
index 00000000..95647abb
--- /dev/null
+++ b/docs/source/siteadmin/about.rst
@@ -0,0 +1,101 @@
+.. 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 in an environment that respects our
+freedom and independence.  In the future MediaGoblin will include
+support other media, like video, and 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/codebase.rst b/docs/source/siteadmin/codebase.rst
new file mode 100644
index 00000000..3ef91290
--- /dev/null
+++ b/docs/source/siteadmin/codebase.rst
@@ -0,0 +1,160 @@
+.. 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/>`_.
+
+
+Software Stack
+==============
+
+* Project infrastructure
+
+  * `Python <http://python.org/>`_: the language we're using to write
+    this
+
+  * `Nose <http://somethingaboutorange.com/mrl/projects/nose/>`_:
+    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
+
+  * `WebOb <http://pythonpaste.org/webob/>`_: nice abstraction layer
+    from HTTP requests, responses and WSGI bits
+
+  * `Routes <http://routes.groovie.org/>`_: for URL routing
+
+  * `Beaker <http://beaker.groovie.org/>`_: for handling sessions and
+    caching
+
+  * `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
+
+
+
+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
+    |  |- tests/
+    |  |- templates/
+    |  |- auth/
+    |  \- submit/
+    |- docs/                     # documentation
+    |- devtools/                 # some scripts for developer convenience
+    |
+    |  # 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/
+    |- user_dev/                 # sessions, etc
+
+
+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
+:models.py:  holds the sqlalchemy schemas---these are the data structures
+             we're working with
+
+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
+``models.py`` in addition to some other code.
diff --git a/docs/source/siteadmin/configuration.rst b/docs/source/siteadmin/configuration.rst
new file mode 100644
index 00000000..a3dafa4c
--- /dev/null
+++ b/docs/source/siteadmin/configuration.rst
@@ -0,0 +1,129 @@
+.. 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::
+
+    #mediagoblin on irc.freenode.net
+
+
+Celery
+======
+
+We should point to another celery-specific section of the document
+actually :)
diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst
new file mode 100644
index 00000000..788b06d7
--- /dev/null
+++ b/docs/source/siteadmin/deploying.rst
@@ -0,0 +1,320 @@
+.. 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.
+
+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 man 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 the method.
+
+Assuming you are going to deploy with FastCGI, you should also install
+flup::
+
+    ./bin/easy_install flup
+
+This concludes the initial configuration of the development
+environment. In the future, you want update your
+codebase, you should also run::
+
+    ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate
+
+Deploy MediaGoblin Services
+---------------------------
+
+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.
+
+Connect the Webserver to MediaGoblin with FastCGI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section describes how to configure MediaGoblin to work via
+FastCGI. Our 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;
+
+     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/;
+     }
+
+     # 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.
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..1cf7f30c
--- /dev/null
+++ b/docs/source/siteadmin/media-types.rst
@@ -0,0 +1,76 @@
+.. 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:
+
+====================
+Enabling Media Types
+====================
+
+In the future, there will be all sorts of media types you can enable,
+but in the meanwhile there are two additional media type: video and
+ascii art.
+
+First, you should probably read ":doc:`configuration`" to make sure
+you know how to modify the mediagoblin config file.
+
+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::
+
+    sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \
+        gstreamer0.10-ffmpeg
+
+Next, modify (and possibly copy over from ``mediagoblin.ini``) your
+``mediagoblin_local.ini``.  In the ``[mediagoblin]`` section, add
+``mediagoblin.media_types.video`` to the ``media_types`` list.
+
+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
+
+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.
+
+
+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::
+
+    ./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
+
+Now any .txt file you uploaded will be processed as ascii art!
diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst
new file mode 100644
index 00000000..41f2970f
--- /dev/null
+++ b/docs/source/siteadmin/plugins.rst
@@ -0,0 +1,137 @@
+=========
+ 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-restrictfive", we would do::
+
+    pip install mediagoblin-restrictfive
+
+.. 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.
+
+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-restrictfive" plugin had the Python
+package path ``restrictfive``, then you would add ``restrictfive`` to
+the ``plugins`` section as a subsection::
+
+    [plugins]
+
+    [[restrictfive]]
+
+
+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.flatpages`` and you would add that
+to your ``.ini`` file like this::
+
+    [plugins]
+
+    [[mediagoblin.plugins.flatpages]]
+    # configuration for flatpages plugin here!
+    directory = /srv/mediagoblin/flatpages
+
+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-restrictfive
+
+.. 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.
diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst
new file mode 100644
index 00000000..1e6631db
--- /dev/null
+++ b/docs/source/siteadmin/production-deployments.rst
@@ -0,0 +1,94 @@
+.. 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 instance configured 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: ::
+
+    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: ::
+
+    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
+---------------
+
+While the ``./lazyserer.sh`` configuration provides an efficient way to
+start using a MediaGoblin instance, it is not suitable for production
+deployments for several reasons:
+
+In nearly every scenario, work on the Celery queue will need to
+balance with the demands of other processes, and cannot proceed
+synchronously. This is a particularly relevant problem if you use
+MediaGoblin to host video content. Processing with Celery ought to be
+operationally separate from the MediaGoblin application itself, this
+simplifies management and support better workload distribution.
+
+Basically, if you're doing anything beyond a trivial workload, such as
+image hosting for a small set of users, or have limited media types
+such as "ASCII art" or icon sharing, you will need to run ``celeryd``
+as a separate process.
+
+Build an :ref:`init script <init-script>` around the following
+command::
+
+    CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
+
+Modify your existing MediaGoblin and application init scripts, if
+necessary, to prevent them from starting their own ``celeryd``
+processes.
+
+.. _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. In the future, MediaGoblin will provide
+example scripts as examples.
+
+.. 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..2efded73
--- /dev/null
+++ b/docs/source/siteadmin/relnotes.rst
@@ -0,0 +1,52 @@
+.. 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
+=============
+
+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.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..7584b688
--- /dev/null
+++ b/docs/source/siteadmin/theming.rst
@@ -0,0 +1,21 @@
+.. 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 haven't implemented the necessary scaffolding to allow for theming
+yet.  Thus, this chapter is a stub.