Moves docs files around so we build from source/ directory

20 files changed, 2179 insertions, 0 deletions

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/_templates/mg_theme/layout.html b/docs/source/_templates/mg_theme/layout.html
new file mode 100644
index 00000000..eccda14b
--- /dev/null
+++ b/docs/source/_templates/mg_theme/layout.html
@@ -0,0 +1,39 @@
+{#
+    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>
+    {% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
+    {%- 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>
+<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-sa/3.0/88x31.png" /></a><br /><span xmlns:dc="http://purl.org/dc/elements/1.1/" href="http://purl.org/dc/dcmitype/Text" property="dc:title" rel="dc:type">{{ shorttitle|e }}</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="http://bluesock.org/~willg/" property="cc:attributionName" rel="cc:attributionURL">Will Kahn-Greene</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.<br />
+    </div>
+
+<script type="text/javascript">
+  var _gaq = _gaq || [];
+  _gaq.push(['_setAccount', 'UA-163840-8']);
+  _gaq.push(['_trackPageview']);
+
+  (function() {
+    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+  })();
+</script>
+{%- endblock %}
diff --git a/docs/source/_templates/mg_theme/static/default.css_t b/docs/source/_templates/mg_theme/static/default.css_t
new file mode 100644
index 00000000..f200a0fe
--- /dev/null
+++ b/docs/source/_templates/mg_theme/static/default.css_t
@@ -0,0 +1,299 @@
+/*
+ * default.css_t
+ * ~~~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- default theme.
+ *
+ * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+@import url("basic.css");
+
+/* -- page layout ----------------------------------------------------------- */
+
+body {
+    font-family: {{ theme_bodyfont }};
+    font-size: 100%;
+    background-color: {{ theme_footerbgcolor }};
+    color: #000;
+    margin: 0;
+    padding: 0;
+}
+
+div.document {
+    background-color: {{ theme_sidebarbgcolor }};
+}
+
+div.documentwrapper {
+    float: left;
+    width: 100%;
+}
+
+div.bodywrapper {
+    margin: 0 0 0 230px;
+}
+
+div.body {
+    background-color: {{ theme_bgcolor }};
+    color: {{ theme_textcolor }};
+    padding: 0 20px 30px 20px;
+}
+
+{%- if theme_rightsidebar|tobool %}
+div.bodywrapper {
+    margin: 0 230px 0 0;
+}
+{%- endif %}
+
+div.footer {
+    color: {{ theme_footertextcolor }};
+    width: 100%;
+    padding: 9px 0 9px 0;
+    text-align: center;
+    font-size: 75%;
+}
+
+div.footer a {
+    color: {{ theme_footertextcolor }};
+    text-decoration: underline;
+}
+
+div.related {
+    background-color: {{ theme_relbarbgcolor }};
+    line-height: 30px;
+    color: {{ theme_relbartextcolor }};
+}
+
+div.related a {
+    color: {{ theme_relbarlinkcolor }};
+}
+
+div.sphinxsidebar {
+    {%- if theme_stickysidebar|tobool %}
+    top: 30px;
+    bottom: 0;
+    margin: 0;
+    position: fixed;
+    overflow: auto;
+    height: auto;
+    {%- endif %}
+    {%- if theme_rightsidebar|tobool %}
+    float: right;
+    {%- if theme_stickysidebar|tobool %}
+    right: 0;
+    {%- endif %}
+    {%- endif %}
+}
+
+{%- if theme_stickysidebar|tobool %}
+/* this is nice, but it it leads to hidden headings when jumping
+   to an anchor */
+/*
+div.related {
+    position: fixed;
+}
+
+div.documentwrapper {
+    margin-top: 30px;
+}
+*/
+{%- endif %}
+
+div.sphinxsidebar h3 {
+    font-family: {{ theme_headfont }};
+    color: {{ theme_sidebartextcolor }};
+    font-size: 1.4em;
+    font-weight: normal;
+    margin: 0;
+    padding: 0;
+}
+
+div.sphinxsidebar h3 a {
+    color: {{ theme_sidebartextcolor }};
+}
+
+div.sphinxsidebar h4 {
+    font-family: {{ theme_headfont }};
+    color: {{ theme_sidebartextcolor }};
+    font-size: 1.3em;
+    font-weight: normal;
+    margin: 5px 0 0 0;
+    padding: 0;
+}
+
+div.sphinxsidebar p {
+    color: {{ theme_sidebartextcolor }};
+}
+
+div.sphinxsidebar p.topless {
+    margin: 5px 10px 10px 10px;
+}
+
+div.sphinxsidebar ul {
+    margin: 10px;
+    padding: 0;
+    color: {{ theme_sidebartextcolor }};
+}
+
+div.sphinxsidebar a {
+    color: {{ theme_sidebarlinkcolor }};
+}
+
+div.sphinxsidebar input {
+    border: 1px solid {{ theme_sidebarlinkcolor }};
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+
+/* -- hyperlink styles ------------------------------------------------------ */
+
+a {
+    color: {{ theme_linkcolor }};
+    text-decoration: none;
+}
+
+a:visited {
+    color: {{ theme_visitedlinkcolor }};
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+{% if theme_externalrefs|tobool %}
+a.external {
+   text-decoration: none;
+   border-bottom: 1px dashed {{ theme_linkcolor }};
+}
+
+a.external:hover {
+   text-decoration: none;
+   border-bottom: none;
+}
+{% endif %}
+
+/* -- body styles ----------------------------------------------------------- */
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+    font-family: {{ theme_headfont }};
+    background-color: {{ theme_headbgcolor }};
+    font-weight: normal;
+    color: {{ theme_headtextcolor }};
+    border-bottom: 1px solid #ccc;
+    margin: 20px -20px 10px -20px;
+    padding: 3px 0 3px 10px;
+}
+
+div.body h1 { margin-top: 0; font-size: 200%; }
+div.body h2 { font-size: 160%; }
+div.body h3 { font-size: 140%; }
+div.body h4 { font-size: 120%; }
+div.body h5 { font-size: 110%; }
+div.body h6 { font-size: 100%; }
+
+a.headerlink {
+    color: {{ theme_headlinkcolor }};
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+}
+
+a.headerlink:hover {
+    background-color: {{ theme_headlinkcolor }};
+    color: white;
+}
+
+div.body p, div.body dd, div.body li {
+    text-align: justify;
+    line-height: 130%;
+}
+
+div.admonition p.admonition-title + p {
+    display: inline;
+}
+
+div.admonition p {
+    margin-bottom: 5px;
+}
+
+div.admonition pre {
+    margin-bottom: 5px;
+}
+
+div.admonition ul, div.admonition ol {
+    margin-bottom: 5px;
+}
+
+div.note {
+    background-color: #eee;
+    border: 1px solid #ccc;
+}
+
+div.seealso {
+    background-color: #ffc;
+    border: 1px solid #ff6;
+}
+
+div.topic {
+    background-color: #eee;
+}
+
+div.warning {
+    background-color: #ffe4e4;
+    border: 1px solid #f66;
+}
+
+p.admonition-title {
+    display: inline;
+}
+
+p.admonition-title:after {
+    content: ":";
+}
+
+pre {
+    padding: 5px;
+    background-color: {{ theme_codebgcolor }};
+    color: {{ theme_codetextcolor }};
+    line-height: 120%;
+    border: 1px solid #ac9;
+    border-left: none;
+    border-right: none;
+}
+
+tt {
+    background-color: #ecf0f3;
+    padding: 0 1px 0 1px;
+    font-size: 0.95em;
+}
+
+th {
+    background-color: #ede;
+}
+
+.warning tt {
+    background: #efc2c2;
+}
+
+.note tt {
+    background: #d6d6d6;
+}
+
+.viewcode-back {
+    font-family: {{ theme_bodyfont }};
+}
+
+div.viewcode-block:target {
+    background-color: #f4debf;
+    border-top: 1px solid #ac9;
+    border-bottom: 1px solid #ac9;
+}
diff --git a/docs/source/_templates/mg_theme/theme.conf b/docs/source/_templates/mg_theme/theme.conf
new file mode 100644
index 00000000..49442e3b
--- /dev/null
+++ b/docs/source/_templates/mg_theme/theme.conf
@@ -0,0 +1,31 @@
+[theme]
+inherit = basic
+stylesheet = default.css
+pygments_style = sphinx
+
+[options]
+rightsidebar = false
+stickysidebar = false
+collapsiblesidebar = false
+externalrefs = false
+
+footerbgcolor    = #b11818
+footertextcolor  = #ffffff
+sidebarbgcolor   = #6a0000
+sidebartextcolor = #ffffff
+sidebarlinkcolor = #98dbcc
+relbarbgcolor    = #b11818
+relbartextcolor  = #ffffff
+relbarlinkcolor  = #ffffff
+bgcolor          = #ffffff
+textcolor        = #000000
+headbgcolor      = #fdeded
+headtextcolor    = #20435c
+headlinkcolor    = #c60f0f
+linkcolor        = #355f7c
+visitedlinkcolor = #355f7c
+codebgcolor      = #eeffcc
+codetextcolor    = #333333
+
+bodyfont = sans-serif
+headfont = 'Trebuchet MS', sans-serif
diff --git a/docs/source/codebase.rst b/docs/source/codebase.rst
new file mode 100644
index 00000000..898eadfe
--- /dev/null
+++ b/docs/source/codebase.rst
@@ -0,0 +1,130 @@
+.. _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 :ref:`hacking-howto`.
+
+
+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
+
+  * `buildout <http://www.buildout.org/>`_: for getting dependencies,
+    building a runtime environment, ...
+
+* Data storage
+
+  * `MongoDB <http://www.mongodb.org/>`_: the document database backend
+    for storage
+
+* 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
+
+  * `Jinja2 <http://jinja.pocoo.org/docs/>`_: the templating engine
+
+  * `MongoKit <http://namlook.github.com/mongokit/>`_: the lightweight
+    ORM for MongoDB we're using which will make it easier to define
+    structures and all that
+
+  * `WTForms <http://wtforms.simplecodes.com/>`_: for handling,
+    validation, and abstraction from HTML forms
+
+  * `Celery <http://celeryproject.org/>`_: for task queuing (resizing
+    images, encoding video, ...)
+
+  * `RabbitMQ <http://www.rabbitmq.com/>`_: for sending tasks to celery
+
+* Front end
+
+  * `JQuery <http://jquery.com/>`_: for groovy JavaScript things
+
+
+
+What's where
+============
+
+After you've run buildout, you're faced with the following directory
+tree::
+
+    mediagoblin/
+    |- mediagoblin/              #source code
+    |  |- tests/
+    |  |- templates/
+    |  |- auth/
+    |  \- submit/
+    |- docs/                     #documentation
+    |
+    |        #the below directories are generated by
+    |        #buildout.
+    |
+    |- bin/                      #scripts
+    |- develop-eggs/
+    |- eggs/
+    |- 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 mongodb 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.
+
+
+Recipes
+=======
+
+FIXME - write this
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 00000000..5861a463
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,239 @@
+# -*- 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('.'))
+
+# -- 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 = ["mgext.youcanhelp"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_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, Free Software Foundation, Inc and 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.
+#
+# The short X.Y version.
+version = '0.0.3'
+# The full version, including alpha/beta/rc tags.
+release = '0.0.3'
+
+# 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'
+
+# 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 = []
+
+# 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 = None
+
+# 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/contributinghowto.rst b/docs/source/contributinghowto.rst
new file mode 100644
index 00000000..06d2814e
--- /dev/null
+++ b/docs/source/contributinghowto.rst
@@ -0,0 +1,185 @@
+.. _contributing-howto-chapter:
+
+====================
+ Contributing HOWTO
+====================
+
+.. contents:: Sections
+   :local:
+
+
+.. _join-the-community-section:
+
+Join the community!
+===================
+
+We're super glad you want to join our community!
+
+See `the join page on the website <http://mediagoblin.org/join/>`_ for
+where we hang out.
+
+There are a variety of ways you can help us and become part of the
+team.  We're not just looking for coders!  We're also looking for
+documentation writers, users, testers, evangelists, user-interface
+designers, graphics designers, user-experience designers, system
+administrators, friends, painters, bakers, candle-stick makers...
+
+Here are some things you can do today:
+
+
+    **Hang out with us**
+
+        You should hang out with us!  We like people like you!
+
+        At a bare minimum, join the `mailing list
+        <http://mediagoblin.org/join/>`_ and say, "Hi!"
+
+        We also hang out on IRC in ``#mediagoblin`` on Freenode.net.
+
+
+    **File bugs**
+
+        Filing bugs is a critical part of any project.  For more
+        information on filing bugs, see :ref:`filing-bugs`.
+
+
+    **Write/Fix some code**
+
+        If you are a coder and you're looking to code, check out the
+        :ref:`hacking-howto`.  We even have tips on *becoming* a coder
+        and we're willing to help you!
+
+
+    **Send encouragement**
+
+        A nice word from you could send someone into a tizzy of
+        productive work.  Ten nice words could complete a feature.
+        One hundred nice words could get us to the next milestone.
+
+        Send it to the `mailing list <http://mediagoblin.org/join/>`_
+        or hop into ``#mediagoblin`` on Freenode.net and let us know.
+
+
+    **Spread the word**
+
+        The seductive call of Free Software services is a powerful
+        one, but many cannot hear it because it's drowned out by the
+        rush hour traffic honking of proprietary walled gardens and
+        faux free services.  Yuck!  Be the sweet chirrup of the bird
+        amidst the din!  Tell others that there is a better way to
+        live!
+
+        FIXME - do we want to talk about ways to spread the word?
+
+        FIXME - how can people notify us that they're spreading the
+        word?
+
+
+We're still working on project infrastructure.  We hope to have the
+bits in place for these additional things to do in the coming months:
+
+    **Become a user**
+
+        We're building GNU MediaGoblin for us and for you but really
+        you're one of us and I am you and we are we and GNU
+        MediaGoblin is the walrus.
+    
+        Sign up for an account.  Use the service.  Relish in the
+        thought that this service comes with a heaping side of Freedom
+        and you can salt and pepper it to your liking.
+
+
+    **Help other users**
+
+        Have you spent time with GNU MediaGoblin?  If so, your
+        experience and wisdom are invaluable and you're the best
+        person we can think of to help other users with their
+        questions.
+
+
+    **Run your own instance**
+
+        Are there things about our instance you want to change?  Are
+        there things about other instances you wish were different?
+        Want to test upcoming changes?  Want to create patches to
+        implement things you need?  That's great---you can run your
+        own instance!
+    
+        For more information on deploying your own instance, see
+        :ref:`deployment-howto`.
+
+
+    **Translate GNU MediaGoblin**
+
+        Knowing more than one language is an important skill.  If you
+        are multi-lingual and are interested in translating GNU
+        MediaGoblin, see :ref:`translating`.
+
+
+    **Create a theme**
+
+        As people deploy their own GNU MediaGoblin instances, good
+        themes are a must have!  For more information on theming, see
+        :ref:`theming-howto`.
+
+
+Contributing thank you drawings / copyright assignment
+======================================================
+
+Copyright assignment with GNU MediaGoblin to the `FSF
+<http://fsf.org>`_ is highly encouraged but not mandatory.  To
+incentivize both this and people to make cool contributions to our
+project, if you make useful contributions to GNU MediaGoblin *and* do
+a copyright assignment to the Free Software Foundation, the founder of
+the project, Chris Webber, will make a custom drawing of a goblin
+dedicated specifically to you.
+
+For why we're doing copyright assignment, see the
+:ref:`design-decisions-chapter`.
+
+
+.. _filing-bugs:
+
+File bugs
+=========
+
+GNU MediaGoblin uses a bug tracker called `Redmine
+<http://www.redmine.org>`_.
+
+The bug tracker is at `<http://bugs.foocorp.net/projects/mediagoblin>`_.
+
+A good bug report has the following things in it:
+
+1. A short summary that's 60 characters or less.
+
+2. A description that describes the issue (bug, feature request, ...)
+   as well as the context.
+
+  * If it's a bug, can you reproduce it?  Is the issue specific to a
+    browser, computer, image, ...?
+
+  * If it's a feature request, are there related links on the Internet
+    for more information?  Would you be willing to help implement or
+    test the feature?
+
+That's it!  When someone looks into the issue and has questions,
+they'll contact you!
+
+If you don't hear from anyone in a couple of weeks, find someone on
+IRC.
+
+
+.. _translating:
+
+Translate GNU MediaGoblin
+=========================
+
+Coming soon when we set up translation infrastructure.
+
+
+Where to go when you get stuck
+==============================
+
+Go to `our Web site <http://mediagoblin.org/>`_ where we list the
+various places we hang out and how to get a hold of us.
+
diff --git a/docs/source/deploymenthowto.rst b/docs/source/deploymenthowto.rst
new file mode 100644
index 00000000..f50edfb6
--- /dev/null
+++ b/docs/source/deploymenthowto.rst
@@ -0,0 +1,16 @@
+.. _deployment-howto:
+
+==================
+ Deployment HOWTO
+==================
+
+Step 1: Write code that can be deployed.
+
+Step 2: ?
+
+Step 3: Write the deployment guide and profit!
+
+But seriously, this is a stub since we're not quite there (yet) but if
+you want to see where we are now, you can try to run the latest
+development version by following the instructions at
+:ref:`hacking-howto`.
diff --git a/docs/source/designdecisions.rst b/docs/source/designdecisions.rst
new file mode 100644
index 00000000..afa1e26b
--- /dev/null
+++ b/docs/source/designdecisions.rst
@@ -0,0 +1,329 @@
+.. _design-decisions-chapter:
+
+==================
+ Design Decisions
+==================
+
+.. contents:: Sections
+   :local:
+
+
+This chapter talks a bit about design decisions.
+
+
+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:: goblin.png
+       :alt: Cute goblin with a beret.
+
+       *Figure 1: Cute goblin with a beret.  llustrated by Chris
+       Webber*
+
+    .. figure:: 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
+===========
+
+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 :ref:`contributing-howto-chapter` for details.
+
+
diff --git a/docs/source/foreword.rst b/docs/source/foreword.rst
new file mode 100644
index 00000000..1d423f08
--- /dev/null
+++ b/docs/source/foreword.rst
@@ -0,0 +1,46 @@
+==========
+ Foreword
+==========
+
+About this manual
+=================
+
+This is the GNU MediaGoblin manual.  This documentation targets the
+following groups of individuals:
+
+* people who want to use the software
+* people who want to deploy the software
+* contributors
+
+This manual is a living document and is in the ``mediagoblin``
+repository in the ``docs/`` directory.
+
+
+Who wrote this documentation?
+=============================
+
+In no particular order:
+
+* Chris
+* Will
+* Deb
+* Greg
+* Karen
+* Matt
+* Asheesh
+
+
+I found an error in the docs---who do I tell?
+=============================================
+
+There are a few ways---please pick the one most convenient to you!
+
+1. Write up a bug report in the bug tracker at http://bugs.foocorp.net/ .
+2. Tell someone on IRC ``#mediagoblin`` on Freenode.
+3. Send an email to Will ``willg at bluesock dot org``.
+
+When you tell us about your issue, please let us know:
+
+* where you are looking (in git?  url of the web-page?)
+* what the issue is
+* your thoughts on how to resolve it
diff --git a/docs/source/git.rst b/docs/source/git.rst
new file mode 100644
index 00000000..bd0f9d52
--- /dev/null
+++ b/docs/source/git.rst
@@ -0,0 +1,224 @@
+==========================
+ Git, Cloning and Patches
+==========================
+
+.. contents:: Sections
+   :local:
+
+
+GNU MediaGoblin uses git for all our version control and we have the
+repositories hosted on `Gitorious <http://gitorious.org/>`_.  We have
+two repositories:
+
+* MediaGoblin software: http://gitorious.org/mediagoblin/mediagoblin
+* MediaGoblin website: http://gitorious.org/mediagoblin/mediagoblin-website
+
+It's most likely you want to look at the software repository--not the
+website one.
+
+The rest of this chapter talks about using the software repository.
+
+
+How to clone the project
+========================
+
+Do::
+
+    git clone git://gitorious.org/mediagoblin/mediagoblin.git
+
+
+How to contribute changes
+=========================
+
+Tie your changes to issues in the issue tracker
+-----------------------------------------------
+
+All patches should be tied to issues in the `issue tracker
+<http://bugs.foocorp.net/projects/mediagoblin/issues>`_.  That makes
+it a lot easier for everyone to track proposed changes and make sure
+your hard work doesn't get dropped on the floor!  If there isn't an
+issue for what you're working on, please create one.  The better the
+description of what it is you're trying to fix/implement, the better
+everyone else is able to understand why you're doing what you're
+doing.
+
+
+Use bugfix branches to make changes
+-----------------------------------
+
+The best way to isolate your changes is to create a branch based off
+of the MediaGoblin repository master branch, do the changes related to
+that one issue there, and then let us know how to get it.
+
+It's much easier on us if you isolate your changes to a branch focused
+on the issue.  Then we don't have to sift through things.
+
+It's much easier on you if you isolate your changes to a branch
+focused on the issue.  Then when we merge your changes in, you just
+have to do a ``git fetch`` and that's it.  This is especially true if
+we reject some of your changes, but accept others or otherwise tweak
+your changes.
+
+Further, if you isolate your changes to a branch, then you can work on
+multiple issues at the same time and they don't conflict with one
+another.
+
+Name your branches using the isue number and something that makes it clear
+what it's about.  For example, if you were working on tagging, you
+might name your branch ``360_tagging``.
+
+
+Properly document your changes
+------------------------------
+
+Include comments in the code.
+
+Write comprehensive commit messages.  The better your commit message
+is at describing what you did and why, the easier it is for us to
+quickly accept your patch.
+
+Write comprehensive comments in the issue tracker about what you're
+doing and why.
+
+
+How to send us your changes
+---------------------------
+
+There are two ways to let us know how to get it:
+
+1. *(preferred)* **push changes to publicly available git clone and
+   let us know where to find it**
+
+   Push your feature/bugfix/issue branch to your publicly available
+   git clone and add a comment to the issue with the url for your
+   clone and the branch to look at.
+
+2. **attaching the patch files to the issue**
+
+   Run::
+
+       git format-patch --stdout <remote>/master > issue_<number>.patch
+       
+   ``format-patch`` creates a patch of all the commits that are in
+   your branch that aren't in ``<remote>/master``.  The ``--stdout``
+   flag causes all this output to go to stdout where it's redirected
+   to a file named ``issue_<number>.patch``.  That file should be
+   based on the issue you're working with.  For example,
+   ``issue_42.patch`` is a good filename and ``issue_42_rev2.patch``
+   is good if you did a revision of it.
+
+   Having said all that, the filename isn't wildly important.
+
+
+Example workflow
+================
+
+Here's an example workflow.
+
+
+Contributing changes
+--------------------
+
+Slartibartfast from the planet Magrathea far off in the universe has
+decided that he is bored with fjords and wants to fix issue 42 (the
+meaning of life bug) and send us the changes.
+
+Slartibartfast has cloned the MediaGoblin repository and his clone
+lives on gitorious.
+
+Slartibartfast works locally.  The remote named ``origin`` points to
+his clone on gitorious.  The remote named ``gmg`` points to the
+MediaGoblin repository.
+
+Slartibartfast does the following:
+
+1. Fetches the latest from the MediaGoblin repository::
+
+       git fetch --all -p
+
+   This tells ``git fetch`` to fetch all the recent data from all of
+   the remotes (``--all``) and prune any branches that have been
+   deleted in the remotes (``-p``).
+
+2. Creates a branch from the tip of the MediaGoblin repository (the
+   remote is named ``gmg``) master branch called ``bug42_meaning_of_life``::
+
+       git checkout -b bug42_meaning_of_life gmg/master
+
+   This creates a new branch (``-b``) named ``bug42_meaning_of_life`` based
+   on the tip of the ``master`` branch of the remote named ``gmg`` and checks
+   it out.
+
+3. Slartibartfast works hard on his changes in the ``bug42_meaning_of_life``
+   branch.  When done, he wants to notify us that he has made changes
+   he wants us to see.
+
+4. Slartibartfast pushes his changes to his clone::
+
+       git push origin bug42_meaning_of_life --set-upstream
+
+   This pushes the changes in the ``bug42_meaning_of_life`` branch to the
+   remote named ``origin``.
+
+5. Slartibartfast adds a comment to issue 42 with the url for his
+   repository and the name of the branch he put the code in.  He also
+   explains what he did and why it addresses the issue.
+
+
+Updating a contribution
+-----------------------
+
+Slartibartfast brushes his hands off with the sense of accomplishment
+that comes with the knowledge of a job well done.  He stands, wanders
+over to get a cup of water, then realizes that he forgot to run the
+unit tests!
+
+He runs the unit tests and discovers there's a bug in the code!
+
+Then he does this:
+
+1. He checks out the ``bug42_meaning_of_life`` branch::
+
+       git checkout bug42_meaning_of_life
+
+2. He fixes the bug and checks it into the ``bug42_meaning_of_life`` branch.
+
+3. He pushes his changes to his clone (the remote is named ``origin``)::
+
+       git push origin bug42_meaning_of_life
+
+4. He adds another comment to issue 42 explaining about the mistake
+   and how he fixed it and that he's pushed the new change to the
+   ``bug42_meaning_of_life`` branch of his publicly available clone.
+
+
+What happens next
+-----------------
+
+Slartibartfast is once again happy with his work.  He finds issue 42
+in the issue tracker and adds a comment saying he submitted a merge
+request with his changes and explains what they are.
+
+Later, someone checks out his code and finds a problem with it.  He
+adds a comment to the issue tracker specifying the problem and asks
+Slartibartfast to fix it.  Slartibartfst goes through the above steps
+again, fixes the issue, pushes it to his ``bug42_meaning_of_life`` branch and adds
+another comment to the issue tracker about how he fixed it.
+
+Later, someone checks out his code and is happy with it.  Someone
+pulls it into the master branch of the MediaGoblin repository and adds
+another comment to the issue and probably closes the issue out.
+
+Slartibartfast is notified of this.  Slartibartfast does a::
+
+   git fetch --all
+
+The changes show up in the ``master`` branch of the ``gmg`` remote.
+Slartibartfast now deletes his ``bug42_meaning_of_life`` branch
+because he doesn't need it anymore.
+
+
+How to learn git
+================
+
+Check out :ref:`hacking-howto-git`!
diff --git a/docs/source/goblin.png b/docs/source/goblin.png
new file mode 100644
index 00000000..e20265e6
--- /dev/null
+++ b/docs/source/goblin.png
diff --git a/docs/source/hackinghowto.rst b/docs/source/hackinghowto.rst
new file mode 100644
index 00000000..caafba53
--- /dev/null
+++ b/docs/source/hackinghowto.rst
@@ -0,0 +1,345 @@
+.. _hacking-howto:
+
+===============
+ Hacking HOWTO
+===============
+
+.. contents:: Sections
+   :local:
+
+
+So you want to hack on GNU MediaGoblin?
+=======================================
+
+First thing to do is check out the `Web site
+<http://mediagoblin.org/join/>`_ where we list all the project
+infrastructure including:
+
+* the IRC channel
+* the mailing list
+* the issue tracker
+
+Additionally, we have information on how to get involved, who to talk
+to, what needs to be worked on, and other things besides!
+
+Second thing to do is take a look at :ref:`codebase-chapter` where
+we've started documenting how GNU MediaGoblin is built and how to add
+new things.
+
+Third you'll need to :ref:`get the requirements
+<get-requirements-section>`.
+
+Fourth, you'll need to build a development environment.  We use buildout,
+but if you want to use virtualenv, there's a set of mediocre not-very-supported
+steps in the `wiki <https://gitorious.org/mediagoblin/pages/Home>`_.
+
+
+.. _get-requirements-section:
+
+Getting requirements
+====================
+
+First, you need to have the following installed before you can build
+an environment for hacking on GNU MediaGoblin:
+
+* Python 2.6 or 2.7  - http://www.python.org/
+
+  You'll need Python as well as the dev files for building modules.
+
+* python-lxml        - http://lxml.de/
+* git                - http://git-scm.com/
+* MongoDB            - http://www.mongodb.org/
+
+If you're running Debian GNU/Linux or a Debian-derived distribution
+such as Mint or Ubuntu, running the following should install these
+requirements::
+
+    sudo apt-get install mongodb git-core python python-dev \
+         python-lxml
+
+On Fedora::
+
+    yum install mongodb-server python-paste-deploy python-paste-script \
+         git-core python python-devel python-lxml
+
+.. YouCanHelp::
+
+   If you have instructions for other GNU/Linux distributions to set
+   up requirements, let us know!
+
+
+.. _hacking-with-buildout:
+
+
+How to set up and maintain an environment for hacking with buildout
+===================================================================
+
+**Requirements**
+
+No additional requirements.
+
+
+**Create a development environment**
+
+After installing the requirements, follow these steps:
+
+1. Clone the repository::
+
+       git clone git://gitorious.org/mediagoblin/mediagoblin.git
+
+2. Bootstrap and run buildout::
+
+       cd mediagoblin
+       python bootstrap.py && ./bin/buildout
+
+
+That's it!  Using this method, buildout should create a ``user_dev``
+directory, in which certain things will be stored (media, beaker
+session stuff, etc).  You can change this, but for development
+purposes this default should be fine.
+
+
+**Updating for dependency changes**
+
+While hacking on GNU MediaGoblin over time, you'll eventually have to
+update your development environment because the dependencies have
+changed.  To do that, run::
+
+    ./bin/buildout && ./bin/gmg migrate
+
+
+**Updating for code changes**
+
+You don't need to do anything---code changes are automatically
+available.
+
+
+**Deleting your buildout**
+
+At some point, you may want to delete your buildout.  Perhaps it's to
+start over.  Perhaps it's to test building development environments
+with buildout.
+
+To do this, do::
+
+    rm -rf bin develop-eggs eggs mediagoblin.egg-info parts user_dev
+
+
+Running the server
+==================
+
+If you want to get things running quickly and without hassle, just
+run::
+
+    ./lazyserver.sh
+
+This will start up a python server where you can begin playing with
+mediagoblin.  It will also run celery in "always eager" mode so you
+don't have to start a separate process for it.
+
+This is fine in development, but if you want to actually run celery
+separately for testing (or deployment purposes), you'll want to run
+the server independently::
+
+    ./bin/paster serve paste.ini --reload
+
+
+Running celeryd
+===============
+
+If you aren't using ./lazyserver.sh or otherwise aren't running celery
+in always eager mode, you'll need to do this if you want your media to
+process and actually show up.  It's probably a good idea in
+development to have the web server (above) running in one terminal and
+celeryd in another window.
+
+Run::
+
+    CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd
+
+
+Running the test suite
+======================
+
+Run::
+
+    ./runtests.sh
+
+
+Running a shell
+===============
+
+If you want a shell with your database pre-setup and an instantiated
+application ready and at your fingertips....
+
+Run::
+
+    ./bin/gmg shell
+
+
+Troubleshooting
+===============
+
+pymongo.errors.AutoReconnect: could not find master/primary
+-----------------------------------------------------------
+
+If you see this::
+
+    pymongo.errors.AutoReconnect: could not find master/primary
+
+then make sure mongodb is installed and running.
+
+If it's installed, check the mongodb log.  On my machine, that's 
+``/var/log/mongodb/mongodb.log``.  If you see something like::
+
+    old lock file: /var/lib/mongodb/mongod.lock.  probably means...
+
+in that case you might have had an unclean shutdown.  Try::
+
+    sudo mongod --repair
+
+If that didn't work, just delete the lock file and relaunch mongodb.
+
+Anyway, then start the mongodb server in whatever way is appropriate
+for your distro / OS.
+
+
+pkg_resources.DistributionNotFound: distribute
+----------------------------------------------
+
+If you get this while running buildout::
+
+   pkg_resources.DistributionNotFound: distribute
+
+Try this commmand instead::
+
+   python bootstrap.py --distribute && ./bin/buildout
+
+
+Wiping your user data
+=====================
+
+.. Note::
+
+   Unless you're doing development and working on and testing creating
+   a new instance, you will probably never have to do this.  Will
+   plans to do this work and thus he documented it.
+
+.. YouCanHelp::
+
+   If you're familiar with MongoDB, we'd love to get a `script that
+   removes all the GNU MediaGoblin data from an existing instance
+   <http://bugs.foocorp.net/issues/296>`_.  Let us know!
+
+
+Quickstart for Django programmers
+=================================
+
+We're not using Django, but the codebase is very Django-like in its
+structure.
+
+* ``routing.py`` is like ``urls.py`` in Django
+* ``models.py`` has mongokit ORM definitions
+* ``views.py`` is where the views go
+
+We're using MongoDB.  Basically, instead of a relational database with
+tables, you have a big JSON structure which acts a lot like a Python
+dict.
+
+
+.. YouCanHelp::
+
+   If there are other things that you think would help orient someone
+   new to GNU MediaGoblin but coming from Django, let us know!
+
+
+Bite-sized bugs to start with
+=============================
+
+**May 3rd, 2011**:  We don't have a list of bite-sized bugs, yet, but
+this is important to us.  If you're interested in things to work on,
+let us know on `the mailing list <http://mediagoblin.org/join/>`_ or
+on the `IRC channel <http://mediagoblin.org/join/>`_.
+
+
+Tips for people new to coding
+=============================
+
+Learning Python
+---------------
+
+GNU MediaGoblin is written using a programming language called `Python
+<http://python.org/>`_.
+
+There are two different incompatible iterations of Python which I'll
+refer to as Python 2 and Python 3.  GNU MediaGoblin is written in
+Python 2 and requires Python 2.6 or 2.7.  At some point, we might
+switch to Python 3, but that's a future thing.
+
+You can learn how to code in Python 2 from several excellent books
+that are freely available on the Internet:
+
+* `Learn Python the Hard Way <http://learnpythonthehardway.org/>`_
+* `Dive Into Pyton <http://diveintopython.org/>`_
+* `Python for Software Design <http://www.greenteapress.com/thinkpython/>`_
+* `A Byte of Python <http://www.swaroopch.com/notes/Python>`_
+
+These are all excellent texts.
+
+.. YouCanHelp::
+
+   If you know of other good quality Python tutorials and Python
+   tutorial videos, let us know!
+
+
+Learning Libraries GNU MediaGoblin uses
+---------------------------------------
+
+GNU MediaGoblin uses a variety of libraries in order to do what it
+does.  These libraries are listed in the :ref:`codebase-chapter`
+along with links to the project Web sites and documentation for the
+libraries.
+
+There are a variety of Python-related conferences every year that have
+sessions covering many aspects of these libraries.  You can find them
+at `Python Miro Community <http://python.mirocommunity.org>`_ [0]_.
+
+.. [0] This is a shameless plug.  Will Kahn-Greene runs Python Miro
+   Community.
+
+If you have questions or need help, find us on the mailing list and on
+IRC.
+
+
+.. _hacking-howto-git:
+
+Learning git
+------------
+
+git is an interesting and very powerful tool.  Like all powerful
+tools, it has a learning curve.
+
+If you're new to git, we highly recommend the following resources for
+getting the hang of it:
+
+* `Learn Git <http://learn.github.com/p/intro.html>`_ --- the GitHub
+  intro to git
+* `Pro Git <http://progit.org/book/>`_ --- fantastic book
+* `Git casts <http://gitcasts.com/>`_ --- screencast covering git
+  usage
+* `Git Reference <http://gitref.org/>`_ --- Git reference that makes
+  it easier to get the hang of git if you're coming from other version
+  control systems
+
+There's also a git mission at `OpenHatch <http://openhatch.org/>`_.
+
+
+Learning other utilities
+------------------------
+
+The `OpenHatch <http://openhatch.org/>`_ site has a series of
+`training missions <http://openhatch.org/missions/>`_ which are
+designed to help you learn how to use these tools.
+
+If you're new to tar, diff, patch and git, we highly recommend you sign
+up with OpenHatch and do the missions.
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 00000000..2f84d6a6
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,32 @@
+.. GNU MediaGoblin documentation master file, created by
+   sphinx-quickstart on Thu Apr  7 20:10:27 2011.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to GNU MediaGoblin's documentation!
+===========================================
+
+Table of Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   foreword
+   mediagoblin
+   contributinghowto
+   deploymenthowto
+   hackinghowto
+   theminghowto
+   git
+   codebase
+   designdecisions
+   vision
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/docs/source/mediagoblin.rst b/docs/source/mediagoblin.rst
new file mode 100644
index 00000000..c437ecc3
--- /dev/null
+++ b/docs/source/mediagoblin.rst
@@ -0,0 +1,70 @@
+=================
+ GNU MediaGoblin
+=================
+
+.. contents:: Sections
+   :local:
+
+
+What is GNU MediaGoblin
+=======================
+
+Three years ago (2008), a number of free software luminaries got
+together at the FSF office to answer the question, "What should
+software freedom look like on the participatory web?"  Those thinkers
+included Richard Stallman---founder of the free software movement and
+instigator of the GNU project, Evan Prodromou---the driving force
+behind Status.net, a highly sucessful federated micro-blogging
+service, and FIXME.
+
+Since that time Identi.ca and Libre.fm have answered the
+freedom-loving web-user's need for micro-blogging and music sharing.
+Now, GNU MediaGoblin is building a format for users to share photos.
+Later versions of MediaGoblin will include support for video and other
+media as well as tools to encourage collaboration on media projects.
+
+
+Why are we doing this?
+======================
+
+Centralization and proprietization of media on the internet is a
+serious problem and makes the web go from a system of extreme
+resilience to a system of frightening fragility.  We believe people
+should be able to own their data and that means someone has to build
+the tools to make it possible.  We decided that in this case, that
+someone would be us!
+ 
+
+Who are you?
+============
+
+Free software activists and folks who have worked on a variety of
+other projects like Libre.fm, GNU Social, Status.net, Miro, Miro
+Community, OpenHatch and other projects as well.  We're admirers and
+contributors.  We're writers and painters.  We're friendly and
+dedicated to computer user freedom.
+
+
+How can I participate?
+======================
+
+See `Get Involved <http://mediagoblin.org/join/>`_ on the website..
+
+
+How is GNU MediaGoblin licensed?
+================================
+
+GNU MediaGoblin software is released under an AGPLv3 license.
+
+See the ``COPYING`` file in the source for details.
+
+
+Is this an official GNU Project?  What does that mean?
+======================================================
+
+We are!  It means that we meet the GNU Project's rigourous standards
+for free software.  To find out more about what that means, check out
+`the GNU site <http://gnu.org/>`_.
+
+Please feel free to contact us with further questions!
+
diff --git a/docs/source/mgext/__init__.py b/docs/source/mgext/__init__.py
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/docs/source/mgext/__init__.py
diff --git a/docs/source/mgext/youcanhelp.py b/docs/source/mgext/youcanhelp.py
new file mode 100644
index 00000000..a99d0e4d
--- /dev/null
+++ b/docs/source/mgext/youcanhelp.py
@@ -0,0 +1,44 @@
+from docutils import nodes
+
+from sphinx.util.compat import Directive, make_admonition
+
+class youcanhelp_node(nodes.Admonition, nodes.Element):
+    pass
+
+class YouCanHelp(Directive):
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {}
+
+    def run(self):
+        ad = make_admonition(
+            youcanhelp_node,
+            self.name,
+            ["You Can Help!"],
+            self.options,
+            self.content,
+            self.lineno,
+            self.content_offset,
+            self.block_text,
+            self.state,
+            self.state_machine)
+        ad[0].line = self.lineno
+        return ad
+
+def visit_youcanhelp_node(self, node):
+    self.visit_admonition(node)
+
+def depart_youcanhelp_node(self, node):
+    self.depart_admonition(node)
+
+def setup(app):
+    app.add_node(
+        youcanhelp_node,
+        html=(visit_youcanhelp_node, depart_youcanhelp_node),
+        latex=(visit_youcanhelp_node, depart_youcanhelp_node),
+        text=(visit_youcanhelp_node, depart_youcanhelp_node)
+        )
+    
+    app.add_directive('youcanhelp', YouCanHelp)
diff --git a/docs/source/snugglygoblin.png b/docs/source/snugglygoblin.png
new file mode 100644
index 00000000..f325ae4b
--- /dev/null
+++ b/docs/source/snugglygoblin.png
diff --git a/docs/source/theminghowto.rst b/docs/source/theminghowto.rst
new file mode 100644
index 00000000..7b40685f
--- /dev/null
+++ b/docs/source/theminghowto.rst
@@ -0,0 +1,8 @@
+.. _theming-howto:
+
+===============
+ Theming HOWTO
+===============
+
+We haven't implemented the necessary scaffolding to allow for theming
+yet.  Thus, this chapter is a stub.
diff --git a/docs/source/vision.rst b/docs/source/vision.rst
new file mode 100644
index 00000000..fad248df
--- /dev/null
+++ b/docs/source/vision.rst
@@ -0,0 +1,142 @@
+=========================================
+ Design Document: GNU MediaGoblin vision
+=========================================
+
+.. Note::
+
+   When we get a wiki, this will get moved there.  It's here for now
+   mostly because we didn't have a better place for it.
+
+.. Note::
+
+   By the time you read this, it's very likely it'll be out of date.
+
+
+This document attempts to describe the envisioned workflow of GNU
+MediaGoblin, from a structural standpoint.  For now, *nothing* in this
+document is probably the eventual, final way that things will work.
+Eventually as things come to exist, this document will hopefully be
+refactored to describe how things *do* work.
+
+This documented on hopes, dreams, rainbows, and unicorns.  And it will
+come to fulfillment through a lot of hard work.  Your hard work and my
+hard work.
+
+
+Look and feel
+=============
+
+Default look and feel
+---------------------
+
+Mairin Duffy made mockups for something called Design Hub.  That
+project did a number of things differently than the way we intend to
+go, but it's probably a good idea to steal a good number of ideas from
+here.
+
+http://mairin.wordpress.com/2010/03/09/another-design-hub-mockup/
+
+
+User profile mockup
+-------------------
+
+Here's an ascii art mockup on how things might look for a user's page::
+
+      _____
+     |_( )_|   USER NAME
+     |  |  |
+     |_/_\_|
+    
+        Recent artwork:
+       ___________________       ___________________________
+      |  ___   ___   ___  |     |_About_User_Name___________|
+      | |pic| |pic| |pic| |     |                           |
+      | |___| |___| |___| |     | Some sort of self-        |
+      |  ___   ___   ___  |     | description probably goes |
+    < | |pic| |pic| |pic| | >   | here                      |
+      | |___| |___| |___| |     |                           |
+      |  ___   ___   ___  |     |                           |
+      | |pic| |pic| |pic| |     |                           |
+      | |___| |___| |___| |     |                           |
+      |___________________|     |___________________________|
+    
+                                 ___________________________ 
+        Recent favorites:       |_Recent_activity___________|
+       ___________________      | New picture: DragonFace   |
+      |  ___   ___   ___  |     |                4/2/2010   |
+      | |pic| |pic| |pic| |     |---------------------------|
+      | |___| |___| |___| |     | Sup yall this is some kind|
+      |  ___   ___   ___  |     | of mini blogpost.  Maybe  |
+    < | |pic| |pic| |pic| | >   | the interface will allow  |
+      | |___| |___| |___| |     | for this?                 |
+      |  ___   ___   ___  |     |___________________________|
+      | |pic| |pic| |pic| |     
+      | |___| |___| |___| |      ___________________________ 
+      |___________________|     |_External_comments_here____|
+                                | Dang!  This stuff rocks   |
+                                |          - Joe 4/2/2010   |
+                                |---------------------------|
+                                | Nice job on the dragon    |
+                                |         - Morgan 4/2/2010 |
+                                '---------------------------'
+
+So there's this type of interface that puts a lot of different types
+of info on the same screen.  I'm not sure that I like it.  It's
+possible we'll go with something much more minimalist.  Maybe we'll go
+with something "tabbed" the way statusnet / http://identi.ca is on
+user pages.
+
+It's possible that we could support multiple profile styles here,
+and you could load whatever profile style you want as set by user
+preferences?
+
+
+Uploading mockup
+----------------
+
+Here's an uploading mockup::
+
+     Upload an image
+    
+     [ Title                                 ]
+    
+     Upload: [                      ] [Browse]
+      ___________________________________________
+     |                                           |
+     |                                           |
+     |                   o0O                     |
+     |                  o   '                    |
+     |                   o_.'                    |
+     |                                           |
+     |             Uploading... OK               | <-,
+     |              Resizing... OK               |   |
+     |                                           | Area replaced w/ resized
+     |                                           | image when done
+     |___________________________________________|
+              ________________
+     License |_CC BY-SA_____|V|
+      ___________________________________________
+     | Description goes here.                    |
+     | You can type it up in here and everything |
+     | and it'll show up under the image.        |
+     |                                           |
+     | Possibly we should allow some kind of     |
+     | markup... maybe markdown?                 |
+     '___________________________________________'
+    
+      __________________________________________
+     |> Advanced                                |
+      ------------------------------------------
+
+
+Customizability
+---------------
+
+General site theming customizability is pretty easy!  Since we're
+using `Jinja <http://jinja.pocoo.org/docs/>`_ we can just set up
+user-overriding directories.
+
+We'll also figure out some sort of way to provide theming "packages",
+eventually.
+
+