Commit | Line | Data |
---|---|---|
473a4431 CAW |
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 | ||
94459ead | 14 | .. _codebase-chapter: |
9d952fdc | 15 | |
94459ead WKG |
16 | ======================== |
17 | Codebase Documentation | |
18 | ======================== | |
34366952 | 19 | |
6729d65a WKG |
20 | .. contents:: Sections |
21 | :local: | |
22 | ||
23 | ||
94459ead WKG |
24 | This chapter covers the libraries that GNU MediaGoblin uses as well as |
25 | various recipes for getting things done. | |
34366952 | 26 | |
9610848c WKG |
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, | |
65e7ce63 | 37 | see `the wiki <http://wiki.mediagoblin.org/>`_. |
9610848c | 38 | |
34366952 | 39 | |
94459ead WKG |
40 | Software Stack |
41 | ============== | |
34366952 WKG |
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 | ||
973f37e9 CAW |
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) | |
34366952 WKG |
55 | |
56 | * Data storage | |
57 | ||
7798f911 WKG |
58 | * `SQLAlchemy <http://sqlalchemy.org/>`_: SQL ORM and database |
59 | interaction library for Python. Currently we support sqlite and | |
60 | postgress as backends. | |
34366952 WKG |
61 | |
62 | * Web application | |
63 | ||
917d4663 | 64 | * `Paste Deploy <http://pythonpaste.org/deploy/>`_ and |
34366952 WKG |
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 | ||
973f37e9 CAW |
73 | * `Beaker <http://beaker.groovie.org/>`_: for handling sessions and |
74 | caching | |
34366952 WKG |
75 | |
76 | * `Jinja2 <http://jinja.pocoo.org/docs/>`_: the templating engine | |
77 | ||
34366952 WKG |
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 | ||
973f37e9 CAW |
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. | |
34366952 WKG |
106 | |
107 | * Front end | |
108 | ||
109 | * `JQuery <http://jquery.com/>`_: for groovy JavaScript things | |
110 | ||
111 | ||
9610848c WKG |
112 | |
113 | What's where | |
114 | ============ | |
115 | ||
973f37e9 CAW |
116 | After you've run checked out mediagoblin and followed the virtualenv |
117 | instantiation instructions, you're faced with the following directory | |
9610848c WKG |
118 | tree:: |
119 | ||
120 | mediagoblin/ | |
917d4663 | 121 | |- mediagoblin/ # source code |
9610848c WKG |
122 | | |- tests/ |
123 | | |- templates/ | |
124 | | |- auth/ | |
125 | | \- submit/ | |
917d4663 | 126 | |- docs/ # documentation |
973f37e9 | 127 | |- devtools/ # some scripts for developer convenience |
9610848c | 128 | | |
973f37e9 | 129 | | # the below directories are installed into your virtualenv checkout |
9610848c | 130 | | |
917d4663 | 131 | |- bin/ # scripts |
9610848c | 132 | |- develop-eggs/ |
973f37e9 CAW |
133 | |- lib/ # python libraries installed into your virtualenv |
134 | |- include/ | |
9610848c WKG |
135 | |- mediagoblin.egg-info/ |
136 | |- parts/ | |
917d4663 | 137 | |- user_dev/ # sessions, etc |
9610848c WKG |
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 | |
fe191ea4 | 147 | :models.py: holds the sqlalchemy schemas---these are the data structures |
9610848c WKG |
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. |