docs/codebase.rst

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