docs/source/siteadmin/codebase.rst

   1 .. MediaGoblin Documentation
   2
   3    Written in 2011, 2012 by MediaGoblin contributors
   4
   5    To the extent possible under law, the author(s) have dedicated all
   6    copyright and related and neighboring rights to this software to
   7    the public domain worldwide. This software is distributed without
   8    any warranty.
   9
  10    You should have received a copy of the CC0 Public Domain
  11    Dedication along with this software. If not, see
  12    <http://creativecommons.org/publicdomain/zero/1.0/>.
  13
  14 .. _codebase-chapter:
  15
  16 ========================
  17  Codebase Documentation
  18 ========================
  19
  20 .. contents:: Sections
  21    :local:
  22
  23
  24 This chapter covers the libraries that GNU MediaGoblin uses as well as
  25 various recipes for getting things done.
  26
  27 .. Note::
  28
  29    This chapter is in flux.  Clearly there are things here that aren't
  30    documented.  If there's something you have questions about, please
  31    ask!
  32
  33    See `the join page on the website <http://mediagoblin.org/join/>`_
  34    for where we hang out.
  35
  36 For more information on how to get started hacking on GNU MediaGoblin,
  37 see `the wiki <http://wiki.mediagoblin.org/>`_.
  38
  39
  40 Software Stack
  41 ==============
  42
  43 * Project infrastructure
  44
  45   * `Python <http://python.org/>`_: the language we're using to write
  46     this
  47
  48   * `Nose <http://somethingaboutorange.com/mrl/projects/nose/>`_:
  49     for unit tests
  50
  51   * `virtualenv <http://www.virtualenv.org/>`_: for setting up an
  52     isolated environment to keep mediagoblin and related packages
  53     (potentially not required if MediaGoblin is packaged for your
  54     distro)
  55
  56 * Data storage
  57
  58   * `SQLAlchemy <http://sqlalchemy.org/>`_: SQL ORM and database
  59     interaction library for Python. Currently we support sqlite and
  60     postgress as backends.
  61
  62 * Web application
  63
  64   * `Paste Deploy <http://pythonpaste.org/deploy/>`_ and
  65     `Paste Script <http://pythonpaste.org/script/>`_: we'll use this for
  66     configuring and launching the application
  67
  68   * `WebOb <http://pythonpaste.org/webob/>`_: nice abstraction layer
  69     from HTTP requests, responses and WSGI bits
  70
  71   * `Routes <http://routes.groovie.org/>`_: for URL routing
  72
  73   * `Beaker <http://beaker.groovie.org/>`_: for handling sessions and
  74     caching
  75
  76   * `Jinja2 <http://jinja.pocoo.org/docs/>`_: the templating engine
  77
  78   * `WTForms <http://wtforms.simplecodes.com/>`_: for handling,
  79     validation, and abstraction from HTML forms
  80
  81   * `Celery <http://celeryproject.org/>`_: for task queuing (resizing
  82     images, encoding video, ...)
  83
  84   * `Babel <http://babel.edgewall.org>`_: Used to extract and compile
  85     translations.
  86
  87   * `Markdown (for python) <http://pypi.python.org/pypi/Markdown>`_:
  88     implementation of `Markdown <http://daringfireball.net/projects/markdown/>`_
  89     text-to-html tool to make it easy for people to write richtext
  90     comments, descriptions, and etc.
  91
  92   * `lxml <http://lxml.de/>`_: nice xml and html processing for
  93     python.
  94
  95 * Media processing libraries
  96
  97   * `Python Imaging Library <http://www.pythonware.com/products/pil/>`_:
  98     used to resize and otherwise convert images for display.
  99
 100   * `GStreamer <http://gstreamer.freedesktop.org/>`_: (Optional, for
 101     video hosting sites only) Used to transcode video, and in the
 102     future, probably audio too.
 103
 104   * `chardet <http://pypi.python.org/pypi/chardet>`_: (Optional, for
 105     ascii art hosting sites only)  Used to make ascii art thumbnails.
 106
 107 * Front end
 108
 109   * `JQuery <http://jquery.com/>`_: for groovy JavaScript things
 110
 111
 112
 113 What's where
 114 ============
 115
 116 After you've run checked out mediagoblin and followed the virtualenv
 117 instantiation instructions, you're faced with the following directory
 118 tree::
 119
 120     mediagoblin/
 121     |- mediagoblin/              # source code
 122     |  |- tests/
 123     |  |- templates/
 124     |  |- auth/
 125     |  \- submit/
 126     |- docs/                     # documentation
 127     |- devtools/                 # some scripts for developer convenience
 128     |
 129     |  # the below directories are installed into your virtualenv checkout
 130     |
 131     |- bin/                      # scripts
 132     |- develop-eggs/
 133     |- lib/                      # python libraries installed into your virtualenv
 134     |- include/
 135     |- mediagoblin.egg-info/
 136     |- parts/
 137     |- user_dev/                 # sessions, etc
 138
 139
 140 As you can see, all the code for GNU MediaGoblin is in the
 141 ``mediagoblin`` directory.
 142
 143 Here are some interesting files and what they do:
 144
 145 :routing.py: maps url paths to views
 146 :views.py:   views handle http requests
 147 :models.py:  holds the sqlalchemy schemas---these are the data structures
 148              we're working with
 149
 150 You'll notice that there are several sub-directories: tests,
 151 templates, auth, submit, ...
 152
 153 ``tests`` holds the unit test code.
 154
 155 ``templates`` holds all the templates for the output.
 156
 157 ``auth`` and ``submit`` are modules that enacpsulate authentication
 158 and media item submission.  If you look in these directories, you'll
 159 see they have their own ``routing.py``, ``view.py``, and
 160 ``models.py`` in addition to some other code.