Merge branch 'master' into f411_new_migrations

[mediagoblin.git] / docs / codebase.rst

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