1 .. MediaGoblin Documentation
3 Written in 2011, 2012 by MediaGoblin contributors
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
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/>.
16 ========================
17 Codebase Documentation
18 ========================
20 .. contents:: Sections
24 This chapter covers the libraries that GNU MediaGoblin uses as well as
25 various recipes for getting things done.
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
33 See `the join page on the website <http://mediagoblin.org/join/>`_
34 for where we hang out.
36 For more information on how to get started hacking on GNU MediaGoblin,
37 see `the wiki <http://wiki.mediagoblin.org/>`_, and specifically, go
39 `Hacking HOWTO <http://wiki.mediagoblin.org/HackingHowto>`_
40 which explains generally how to get going with running an instance for
47 After you've run checked out mediagoblin and followed the virtualenv
48 instantiation instructions, you're faced with the following directory
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
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
69 |- docs/ # documentation
70 |- devtools/ # some scripts for developer convenience
72 |- user_dev/ # local instance sessions, media, etc
74 | # the below directories are installed into your virtualenv checkout
78 |- lib/ # python libraries installed into your virtualenv
80 |- mediagoblin.egg-info/
84 As you can see, all the code for GNU MediaGoblin is in the
85 ``mediagoblin`` directory.
87 Here are some interesting files and what they do:
89 :routing.py: maps url paths to views
90 :views.py: views handle http requests
91 :forms.py: wtforms stuff for this submodule
93 You'll notice that there are several sub-directories: tests,
94 templates, auth, submit, ...
96 ``tests`` holds the unit test code.
98 ``templates`` holds all the templates for the output.
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.
105 You'll also notice that mediagoblin/db/ contains quite a few things,
106 including the following:
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
117 * Project infrastructure
119 * `Python <http://python.org/>`_: the language we're using to write
122 * `Nose <http://somethingaboutorange.com/mrl/projects/nose/>`_:
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
132 * `SQLAlchemy <http://sqlalchemy.org/>`_: SQL ORM and database
133 interaction library for Python. Currently we support sqlite and
134 postgress as backends.
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
142 * `werkzeug <http://werkzeug.pocoo.org/>`_: nice abstraction layer
143 from HTTP requests, responses and WSGI bits
145 * `Beaker <http://beaker.groovie.org/>`_: for handling sessions and
148 * `Jinja2 <http://jinja.pocoo.org/docs/>`_: the templating engine
150 * `WTForms <http://wtforms.simplecodes.com/>`_: for handling,
151 validation, and abstraction from HTML forms
153 * `Celery <http://celeryproject.org/>`_: for task queuing (resizing
154 images, encoding video, ...)
156 * `Babel <http://babel.edgewall.org>`_: Used to extract and compile
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.
164 * `lxml <http://lxml.de/>`_: nice xml and html processing for
167 * Media processing libraries
169 * `Python Imaging Library <http://www.pythonware.com/products/pil/>`_:
170 used to resize and otherwise convert images for display.
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.
176 * `chardet <http://pypi.python.org/pypi/chardet>`_: (Optional, for
177 ascii art hosting sites only) Used to make ascii art thumbnails.
181 * `JQuery <http://jquery.com/>`_: for groovy JavaScript things