.. 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

  * `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.