Merge branch 'master' into joar-skip_transcoding

Conflicts:
	mediagoblin/config_spec.ini

8 files changed, 227 insertions, 10 deletions

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 4209acc8..0b2bccac 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -26,7 +26,8 @@ sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
+intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None)}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['source/_templates']
diff --git a/docs/source/siteadmin/codebase.rst b/docs/source/devel/codebase.rst
index 73e938e7..73e938e7 100644
--- a/docs/source/siteadmin/codebase.rst
+++ b/docs/source/devel/codebase.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
index ac8bd110..abd891a0 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -44,7 +44,6 @@ MediaGoblin website.  It is written for site administrators.
    siteadmin/relnotes
    siteadmin/theming
    siteadmin/plugins
-   siteadmin/codebase
 
 
 .. _core-plugin-section:
@@ -58,6 +57,7 @@ Part 2: Core plugin documentation
    plugindocs/flatpagesfile
    plugindocs/sampleplugin
    plugindocs/oauth
+   plugindocs/trim_whitespace
 
 
 Part 3: Plugin Writer's Guide
@@ -70,6 +70,19 @@ This guide covers writing new GNU MediaGoblin plugins.
 
    pluginwriter/foreward
    pluginwriter/quickstart
+   pluginwriter/database
+   pluginwriter/api
+
+
+Part 4: Developer's Zone
+========================
+
+This chapter contains various information for developers.
+
+.. toctree::
+   :maxdepth: 1
+
+   devel/codebase
 
 
 Indices and tables
diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst
new file mode 100644
index 00000000..42dc3a3d
--- /dev/null
+++ b/docs/source/pluginwriter/api.rst
@@ -0,0 +1,24 @@
+.. MediaGoblin Documentation
+
+   Written in 2013 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+
+==========
+Plugin API
+==========
+
+:mod:`pluginapi` Module
+-----------------------
+
+.. automodule:: mediagoblin.tools.pluginapi
+   :members: get_config, register_routes, register_template_path,
+             register_template_hooks, get_hook_templates
diff --git a/docs/source/pluginwriter/database.rst b/docs/source/pluginwriter/database.rst
new file mode 100644
index 00000000..58edf3a0
--- /dev/null
+++ b/docs/source/pluginwriter/database.rst
@@ -0,0 +1,111 @@
+.. MediaGoblin Documentation
+
+   Written in 2013 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+
+========
+Database
+========
+
+
+Accessing Existing Data
+=======================
+
+If your plugin wants to access existing data, this is quite
+straight forward. Just import the appropiate models and use
+the full power of SQLAlchemy. Take a look at the (upcoming)
+database section in the Developer's Chapter.
+
+
+Creating new Tables
+===================
+
+If your plugin needs some new space to store data, you
+should create a new table.  Please do not modify core
+tables.  Not doing so might seem inefficient and possibly
+is.  It will help keep things sane and easier to upgrade
+versions later.
+
+So if you create a new plugin and need new tables, create a
+file named ``models.py`` in your plugin directory. You
+might take a look at the core's db.models for some ideas.
+Here's a simple one:
+
+.. code-block:: python
+
+    from mediagoblin.db.base import Base
+    from sqlalchemy import Column, Integer, Unicode, ForeignKey
+
+    class MediaSecurity(Base):
+        __tablename__ = "yourplugin__media_security"
+
+        # The primary key *and* reference to the main media_entry
+        media_entry = Column(Integer, ForeignKey('core__media_entries.id'),
+            primary_key=True)
+        get_media_entry = relationship("MediaEntry",
+            backref=backref("security_rating", cascade="all, delete-orphan"))
+
+        rating = Column(Unicode)
+
+    MODELS = [MediaSecurity]
+
+That's it.
+
+Some notes:
+
+* Make sure all your ``__tablename__`` start with your
+  plugin's name so the tables of various plugins can't
+  conflict in the database. (Conflicts in python naming are
+  much easier to fix later).
+* Try to get your database design as good as possible in
+  the first attempt.  Changing the database design later,
+  when people already have data using the old design, is
+  possible (see next chapter), but it's not easy.
+
+
+Changing the Database Schema Later
+==================================
+
+If your plugin is in use and instances use it to store some
+data, changing the database design is a tricky thing.
+
+1. Make up your mind how the new schema should look like.
+2. Change ``models.py`` to contain the new schema. Keep a
+   copy of the old version around for your personal
+   reference later.
+3. Now make up your mind (possibly using your old and new
+   ``models.py``) what steps in SQL are needed to convert
+   the old schema to the new one.
+   This is called a "migration".
+4. Create a file ``migrations.py`` that will contain all
+   your migrations and add your new migration.
+
+Take a look at the core's ``db/migrations.py`` for some
+good examples on what you might be able to do. Here's a
+simple one to add one column:
+
+.. code-block:: python
+
+    from mediagoblin.db.migration_tools import RegisterMigration, inspect_table
+    from sqlalchemy import MetaData, Column, Integer
+
+    MIGRATIONS = {}
+
+    @RegisterMigration(1, MIGRATIONS)
+    def add_license_preference(db):
+        metadata = MetaData(bind=db.bind)
+
+        security_table = inspect_table(metadata, 'yourplugin__media_security')
+
+        col = Column('security_level', Integer)
+        col.create(security_table)
+        db.commit()
diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst
index 91406f96..9b2324ae 100644
--- a/docs/source/siteadmin/deploying.rst
+++ b/docs/source/siteadmin/deploying.rst
@@ -282,6 +282,10 @@ this ``nginx.conf`` file should be modeled on the following::
      # Change this to update the upload size limit for your users
      client_max_body_size 8m;
 
+     # prevent attacks (someone uploading a .txt file that the browser
+     # interprets as an HTML file, etc.)
+     add_header X-Content-Type-Options nosniff;
+
      server_name mediagoblin.example.org www.mediagoblin.example.org;
      access_log /var/log/nginx/mediagoblin.example.access.log;
      error_log /var/log/nginx/mediagoblin.example.error.log;
diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst
index 8fbce5e4..23d3f3b9 100644
--- a/docs/source/siteadmin/media-types.rst
+++ b/docs/source/siteadmin/media-types.rst
@@ -71,16 +71,24 @@ 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::
+good/bad/ugly).  On Debianoid systems
 
-    sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \
+.. code-block:: bash
+
+    sudo apt-get install python-gst0.10 \
+        gstreamer0.10-plugins-base \
+        gstreamer0.10-plugins-bad \
+        gstreamer0.10-plugins-good \
+        gstreamer0.10-plugins-ugly \
         gstreamer0.10-ffmpeg
 
 
 Add ``mediagoblin.media_types.video`` to the ``media_types`` list in your
 ``mediagoblin_local.ini`` and restart MediaGoblin.
 
-Run::
+Run
+
+.. code-block:: bash
 
     ./bin/gmg dbupdate
 
@@ -108,7 +116,9 @@ To install these on Debianoid systems, run::
 
 The ``scikits.audiolab`` package you will install in the next step depends on the
 ``libsndfile1-dev`` package, so we should install it.
-On Debianoid systems, run::
+On Debianoid systems, run
+
+.. code-block:: bash
 
     sudo apt-get install libsndfile1-dev
 
@@ -126,7 +136,9 @@ Then install ``scikits.audiolab`` for the spectrograms::
 Add ``mediagoblin.media_types.audio`` to the ``media_types`` list in your
 ``mediagoblin_local.ini`` and restart MediaGoblin.
 
-Run::
+Run
+
+.. code-block:: bash
 
     ./bin/gmg dbupdate
 
@@ -138,7 +150,9 @@ 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::
+library, which is necessary for creating thumbnails of ascii art
+
+.. code-block:: bash
 
     ./bin/easy_install chardet
 
@@ -152,7 +166,9 @@ the list would look like this::
 
     media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii
 
-Run::
+Run
+
+.. code-block:: bash
 
     ./bin/gmg dbupdate
 
@@ -171,7 +187,9 @@ is surely not to work prior to Blender 2.5X).
 Add ``mediagoblin.media_types.stl`` to the ``media_types`` list in your
 ``mediagoblin_local.ini`` and restart MediaGoblin. 
 
-Run::
+Run
+
+.. code-block:: bash
 
     ./bin/gmg dbupdate
 
diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst
index 356fab7f..0ed5ac6a 100644
--- a/docs/source/siteadmin/production-deployments.rst
+++ b/docs/source/siteadmin/production-deployments.rst
@@ -77,6 +77,52 @@ Modify your existing MediaGoblin and application init scripts, if
 necessary, to prevent them from starting their own ``celeryd``
 processes.
 
+Monitor exceptions
+------------------
+
+This is an example config using raven_ to report exceptions and
+:py:mod:`logging` messages to a sentry_ instance
+
+.. _raven: http://raven.readthedocs.org/
+.. _sentry: https://github.com/getsentry
+
+.. code-block:: ini
+
+    [pipeline:main]
+    pipeline =
+        errors
+        raven
+        routing
+
+    [loggers]
+    keys = root, sentry
+
+    [handlers]
+    keys = console, sentry
+
+    [formatters]
+    keys = generic
+
+    [logger_root]
+    level = INFO
+    handlers = console, sentry
+
+    [logger_sentry]
+    level = WARN
+    handlers = console
+    qualname = sentry.errors
+    propagate = 0
+
+    [handler_sentry]
+    class = raven.handlers.logging.SentryHandler
+    args = ('http://public:secret@example.com/1',)
+    level = WARNING
+    formatter = generic
+
+    [filter:raven]
+    use = egg:raven#raven
+    dsn = http://71727ea2c69043e4bbcd793bb0115cd4:e9cedccb32d9482d81f99eeca8b1ad30@sentry.talka.tv/3
+
 .. _init-script:
 
 Use an Init Script