docs/codebase.rst

   1 .. _codebase-chapter:
   2
   3 ========================
   4  Codebase Documentation
   5 ========================
   6
   7 This chapter covers the libraries that GNU MediaGoblin uses as well as
   8 various recipes for getting things done.
   9
  10 .. Note::
  11
  12    This chapter is in flux.  Clearly there are things here that aren't
  13    documented.  If there's something you have questions about, please
  14    ask!
  15
  16    See `the join page on the website <http://mediagoblin.org/join/>`_
  17    for where we hang out.
  18
  19 For more information on how to get started hacking on GNU MediaGoblin,
  20 see :ref:`hacking-howto`.
  21
  22
  23 Software Stack
  24 ==============
  25
  26 * Project infrastructure
  27
  28   * `Python <http://python.org/>`_: the language we're using to write
  29     this
  30
  31   * `Nose <http://somethingaboutorange.com/mrl/projects/nose/>`_:
  32     for unit tests
  33
  34   * `buildout <http://www.buildout.org/>`_: for getting dependencies,
  35     building a runtime environment, ...
  36
  37 * Data storage
  38
  39   * `MongoDB <http://www.mongodb.org/>`_: the document database backend
  40     for storage
  41
  42 * Web application
  43
  44   * `Paste Deploy <http://pythonpaste.org/deploy/>`_ and
  45     `Paste Script <http://pythonpaste.org/script/>`_: we'll use this for
  46     configuring and launching the application
  47
  48   * `WebOb <http://pythonpaste.org/webob/>`_: nice abstraction layer
  49     from HTTP requests, responses and WSGI bits
  50
  51   * `Routes <http://routes.groovie.org/>`_: for URL routing
  52
  53   * `Beaker <http://beaker.groovie.org/>`_: for handling sessions
  54
  55   * `Jinja2 <http://jinja.pocoo.org/docs/>`_: the templating engine
  56
  57   * `MongoKit <http://namlook.github.com/mongokit/>`_: the lightweight
  58     ORM for MongoDB we're using which will make it easier to define
  59     structures and all that
  60
  61   * `WTForms <http://wtforms.simplecodes.com/>`_: for handling,
  62     validation, and abstraction from HTML forms
  63
  64   * `Celery <http://celeryproject.org/>`_: for task queuing (resizing
  65     images, encoding video, ...)
  66
  67   * `RabbitMQ <http://www.rabbitmq.com/>`_: for sending tasks to celery
  68
  69 * Front end
  70
  71   * `JQuery <http://jquery.com/>`_: for groovy JavaScript things
  72
  73
  74
  75 What's where
  76 ============
  77
  78 After you've run buildout, you're faced with the following directory
  79 tree::
  80
  81     mediagoblin/
  82     |- mediagoblin/              #source code
  83     |  |- tests/
  84     |  |- templates/
  85     |  |- auth/
  86     |  \- submit/
  87     |- docs/                     #documentation
  88     |
  89     |        #the below directories are generated by
  90     |        #buildout.
  91     |
  92     |- bin/                      #scripts
  93     |- develop-eggs/
  94     |- eggs/
  95     |- mediagoblin.egg-info/
  96     |- parts/
  97     |- user_dev/                 #sessions, etc
  98
  99
 100 As you can see, all the code for GNU MediaGoblin is in the
 101 ``mediagoblin`` directory.
 102
 103 Here are some interesting files and what they do:
 104
 105 :routing.py: maps url paths to views
 106 :views.py:   views handle http requests
 107 :models.py:  holds the mongodb schemas---these are the data structures
 108              we're working with
 109
 110 You'll notice that there are several sub-directories: tests,
 111 templates, auth, submit, ...
 112
 113 ``tests`` holds the unit test code.
 114
 115 ``templates`` holds all the templates for the output.
 116
 117 ``auth`` and ``submit`` are modules that enacpsulate authentication
 118 and media item submission.  If you look in these directories, you'll
 119 see they have their own ``routing.py``, ``view.py``, and
 120 ``models.py`` in addition to some other code.
 121
 122
 123 Recipes
 124 =======
 125
 126 FIXME - write this