docs/source/devel/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/>`_, and specifically, go
  38 through the
  39 `Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_
  40 which explains generally how to get going with running an instance for
  41 development.
  42
  43
  44 What's where
  45 ============
  46
  47 After you've run checked out mediagoblin and followed the virtualenv
  48 instantiation instructions, you're faced with the following directory
  49 tree::
  50
  51     mediagoblin/
  52     |- mediagoblin/              # source code
  53     |  |- db/                    # database setup
  54     |  |- tools/                 # various utilities
  55     |  |- init/                  # "initialization" tools (arguably should be in tools/)
  56     |  |- tests/                 # unit tests
  57     |  |- templates/             # templates for this application
  58     |  |- media_types/           # code for processing, displaying different media
  59     |  |- storage/               # different storage backends
  60     |  |- gmg_commands/          # command line tools (./bin/gmg)
  61     |  |- themes/                # pre-bundled themes
  62     |  |
  63     |  |  # ... some submodules here as well for different sections
  64     |  |  # of the application... here's just a few
  65     |  |- auth/                  # authentication (login/registration) code
  66     |  |- user_dev/              # user pages (under /u/), including media pages
  67     |  \- submit/                # submitting media for processing
  68     |
  69     |- docs/                     # documentation
  70     |- devtools/                 # some scripts for developer convenience
  71     |
  72     |- user_dev/                 # local instance sessions, media, etc
  73     |
  74     |  # the below directories are installed into your virtualenv checkout
  75     |
  76     |- bin/                      # scripts
  77     |- develop-eggs/
  78     |- lib/                      # python libraries installed into your virtualenv
  79     |- include/
  80     |- mediagoblin.egg-info/
  81     \- parts/
  82
  83
  84 As you can see, all the code for GNU MediaGoblin is in the
  85 ``mediagoblin`` directory.
  86
  87 Here are some interesting files and what they do:
  88
  89 :routing.py: maps url paths to views
  90 :views.py:   views handle http requests
  91 :forms.py:   wtforms stuff for this submodule
  92
  93 You'll notice that there are several sub-directories: tests,
  94 templates, auth, submit, ...
  95
  96 ``tests`` holds the unit test code.
  97
  98 ``templates`` holds all the templates for the output.
  99
 100 ``auth`` and ``submit`` are modules that enacpsulate authentication
 101 and media item submission.  If you look in these directories, you'll
 102 see they have their own ``routing.py``, ``view.py``, and forms.py in
 103 addition to some other code.
 104
 105 You'll also notice that mediagoblin/db/ contains quite a few things,
 106 including the following:
 107
 108 :models.py:      This is where the database is set up
 109 :mixin.py:       Certain functions appended to models from here
 110 :migrations.py:  When creating a new migration (a change to the
 111                  database structure), we put it here
 112
 113
 114 Software Stack
 115 ==============
 116
 117 * Project infrastructure
 118
 119   * `Python <http://python.org/>`_: the language we're using to write
 120     this
 121
 122   * `Py.Test <http://pytest.org/>`_:
 123     for unit tests
 124
 125   * `virtualenv <http://www.virtualenv.org/>`_: for setting up an
 126     isolated environment to keep mediagoblin and related packages
 127     (potentially not required if MediaGoblin is packaged for your
 128     distro)
 129
 130 * Data storage
 131
 132   * `SQLAlchemy <http://sqlalchemy.org/>`_: SQL ORM and database
 133     interaction library for Python. Currently we support sqlite and
 134     postgress as backends.
 135
 136 * Web application
 137
 138   * `Paste Deploy <http://pythonpaste.org/deploy/>`_ and
 139     `Paste Script <http://pythonpaste.org/script/>`_: we'll use this for
 140     configuring and launching the application
 141
 142   * `werkzeug <http://werkzeug.pocoo.org/>`_: nice abstraction layer
 143     from HTTP requests, responses and WSGI bits
 144
 145   * `itsdangerous <http://pythonhosted.org/itsdangerous/>`_:
 146     for handling sessions
 147
 148   * `Jinja2 <http://jinja.pocoo.org/docs/>`_: the templating engine
 149
 150   * `WTForms <http://wtforms.simplecodes.com/>`_: for handling,
 151     validation, and abstraction from HTML forms
 152
 153   * `Celery <http://celeryproject.org/>`_: for task queuing (resizing
 154     images, encoding video, ...)
 155
 156   * `Babel <http://babel.edgewall.org>`_: Used to extract and compile
 157     translations.
 158
 159   * `Markdown (for python) <http://pypi.python.org/pypi/Markdown>`_:
 160     implementation of `Markdown <http://daringfireball.net/projects/markdown/>`_
 161     text-to-html tool to make it easy for people to write richtext
 162     comments, descriptions, and etc.
 163
 164   * `lxml <http://lxml.de/>`_: nice xml and html processing for
 165     python.
 166
 167 * Media processing libraries
 168
 169   * `Python Imaging Library <http://www.pythonware.com/products/pil/>`_:
 170     used to resize and otherwise convert images for display.
 171
 172   * `GStreamer <http://gstreamer.freedesktop.org/>`_: (Optional, for
 173     video hosting sites only) Used to transcode video, and in the
 174     future, probably audio too.
 175
 176   * `chardet <http://pypi.python.org/pypi/chardet>`_: (Optional, for
 177     ascii art hosting sites only)  Used to make ascii art thumbnails.
 178
 179 * Front end
 180
 181   * `JQuery <http://jquery.com/>`_: for groovy JavaScript things
 182
 183