From 3214c653dd72605ecacfffe13d1972c2c88506c1 Mon Sep 17 00:00:00 2001 From: Elrond Date: Sat, 26 Jan 2013 19:20:18 +0100 Subject: Docs: Create new area for developers. We need some "Part" for developers. Currently, it's named "Part 4: Developer's Zone". But we should come up with a better name soon. Moved the codebase docs in there for starters. --- docs/source/devel/codebase.rst | 158 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 docs/source/devel/codebase.rst (limited to 'docs/source/devel/codebase.rst') diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst new file mode 100644 index 00000000..73e938e7 --- /dev/null +++ b/docs/source/devel/codebase.rst @@ -0,0 +1,158 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +.. _codebase-chapter: + +======================== + Codebase Documentation +======================== + +.. contents:: Sections + :local: + + +This chapter covers the libraries that GNU MediaGoblin uses as well as +various recipes for getting things done. + +.. Note:: + + This chapter is in flux. Clearly there are things here that aren't + documented. If there's something you have questions about, please + ask! + + See `the join page on the website `_ + for where we hang out. + +For more information on how to get started hacking on GNU MediaGoblin, +see `the wiki `_. + + +Software Stack +============== + +* Project infrastructure + + * `Python `_: the language we're using to write + this + + * `Nose `_: + for unit tests + + * `virtualenv `_: for setting up an + isolated environment to keep mediagoblin and related packages + (potentially not required if MediaGoblin is packaged for your + distro) + +* Data storage + + * `SQLAlchemy `_: SQL ORM and database + interaction library for Python. Currently we support sqlite and + postgress as backends. + +* Web application + + * `Paste Deploy `_ and + `Paste Script `_: we'll use this for + configuring and launching the application + + * `werkzeug `_: nice abstraction layer + from HTTP requests, responses and WSGI bits + + * `Beaker `_: for handling sessions and + caching + + * `Jinja2 `_: the templating engine + + * `WTForms `_: for handling, + validation, and abstraction from HTML forms + + * `Celery `_: for task queuing (resizing + images, encoding video, ...) + + * `Babel `_: Used to extract and compile + translations. + + * `Markdown (for python) `_: + implementation of `Markdown `_ + text-to-html tool to make it easy for people to write richtext + comments, descriptions, and etc. + + * `lxml `_: nice xml and html processing for + python. + +* Media processing libraries + + * `Python Imaging Library `_: + used to resize and otherwise convert images for display. + + * `GStreamer `_: (Optional, for + video hosting sites only) Used to transcode video, and in the + future, probably audio too. + + * `chardet `_: (Optional, for + ascii art hosting sites only) Used to make ascii art thumbnails. + +* Front end + + * `JQuery `_: for groovy JavaScript things + + + +What's where +============ + +After you've run checked out mediagoblin and followed the virtualenv +instantiation instructions, you're faced with the following directory +tree:: + + mediagoblin/ + |- mediagoblin/ # source code + | |- tests/ + | |- templates/ + | |- auth/ + | \- submit/ + |- docs/ # documentation + |- devtools/ # some scripts for developer convenience + | + | # the below directories are installed into your virtualenv checkout + | + |- bin/ # scripts + |- develop-eggs/ + |- lib/ # python libraries installed into your virtualenv + |- include/ + |- mediagoblin.egg-info/ + |- parts/ + |- user_dev/ # sessions, etc + + +As you can see, all the code for GNU MediaGoblin is in the +``mediagoblin`` directory. + +Here are some interesting files and what they do: + +:routing.py: maps url paths to views +:views.py: views handle http requests +:models.py: holds the sqlalchemy schemas---these are the data structures + we're working with + +You'll notice that there are several sub-directories: tests, +templates, auth, submit, ... + +``tests`` holds the unit test code. + +``templates`` holds all the templates for the output. + +``auth`` and ``submit`` are modules that enacpsulate authentication +and media item submission. If you look in these directories, you'll +see they have their own ``routing.py``, ``view.py``, and +``models.py`` in addition to some other code. -- cgit v1.2.3 From 6b92dca59d450004d65b4dfb7a81685f8b10ea10 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 17 Mar 2013 14:16:19 -0500 Subject: Better description of the structure of the application --- docs/source/devel/codebase.rst | 41 +++++++++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 10 deletions(-) (limited to 'docs/source/devel/codebase.rst') diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst index 73e938e7..5e8cbcc6 100644 --- a/docs/source/devel/codebase.rst +++ b/docs/source/devel/codebase.rst @@ -117,13 +117,27 @@ tree:: mediagoblin/ |- mediagoblin/ # source code - | |- tests/ - | |- templates/ - | |- auth/ - | \- submit/ + | |- db/ # database setup + | |- tools/ # various utilities + | |- init/ # "initialization" tools (arguably should be in tools/) + | |- tests/ # unit tests + | |- templates/ # templates for this application + | |- media_types/ # code for processing, displaying different media + | |- storage/ # different storage backends + | |- gmg_commands/ # command line tools (./bin/gmg) + | |- themes/ # pre-bundled themes + | | + | | # ... some submodules here as well for different sections + | | # of the application... here's just a few + | |- auth/ # authentication (login/registration) code + | |- user_dev/ # user pages (under /u/), including media pages + | \- submit/ # submitting media for processing + | |- docs/ # documentation |- devtools/ # some scripts for developer convenience | + |- user_dev/ # local instance sessions, media, etc + | | # the below directories are installed into your virtualenv checkout | |- bin/ # scripts @@ -131,8 +145,7 @@ tree:: |- lib/ # python libraries installed into your virtualenv |- include/ |- mediagoblin.egg-info/ - |- parts/ - |- user_dev/ # sessions, etc + \- parts/ As you can see, all the code for GNU MediaGoblin is in the @@ -142,8 +155,7 @@ Here are some interesting files and what they do: :routing.py: maps url paths to views :views.py: views handle http requests -:models.py: holds the sqlalchemy schemas---these are the data structures - we're working with +:forms.py: wtforms stuff for this submodule You'll notice that there are several sub-directories: tests, templates, auth, submit, ... @@ -154,5 +166,14 @@ templates, auth, submit, ... ``auth`` and ``submit`` are modules that enacpsulate authentication and media item submission. If you look in these directories, you'll -see they have their own ``routing.py``, ``view.py``, and -``models.py`` in addition to some other code. +see they have their own ``routing.py``, ``view.py``, and forms.py in +addition to some other code. + +You'll also notice that mediagoblin/db/ contains quite a few things, +including the following: + +:models.py: This is where the database is set up +:mixin.py: Certain functions appended to models from here +:migrations.py: When creating a new migration (a change to the + database structure), we put it here + -- cgit v1.2.3 From d40bce85945ab242caa62c1e269f477a6f4ca8b9 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 18 Mar 2013 08:50:29 -0500 Subject: Point to the Hacking HOWTO --- docs/source/devel/codebase.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/source/devel/codebase.rst') diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst index 5e8cbcc6..98e0c26e 100644 --- a/docs/source/devel/codebase.rst +++ b/docs/source/devel/codebase.rst @@ -34,7 +34,11 @@ various recipes for getting things done. for where we hang out. For more information on how to get started hacking on GNU MediaGoblin, -see `the wiki `_. +see `the wiki `_, and specifically, go +through the +`Hacking HOWTO `_ +which explains generally how to get going with running an instance for +development. Software Stack -- cgit v1.2.3 From 9430b957e43575df73fec2054079cfef2ef589f4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 21 Mar 2013 10:08:09 -0500 Subject: Move description of software stack below description of "What's where" --- docs/source/devel/codebase.rst | 140 ++++++++++++++++++++--------------------- 1 file changed, 70 insertions(+), 70 deletions(-) (limited to 'docs/source/devel/codebase.rst') diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst index 98e0c26e..cd46242c 100644 --- a/docs/source/devel/codebase.rst +++ b/docs/source/devel/codebase.rst @@ -41,6 +41,76 @@ which explains generally how to get going with running an instance for development. +What's where +============ + +After you've run checked out mediagoblin and followed the virtualenv +instantiation instructions, you're faced with the following directory +tree:: + + mediagoblin/ + |- mediagoblin/ # source code + | |- db/ # database setup + | |- tools/ # various utilities + | |- init/ # "initialization" tools (arguably should be in tools/) + | |- tests/ # unit tests + | |- templates/ # templates for this application + | |- media_types/ # code for processing, displaying different media + | |- storage/ # different storage backends + | |- gmg_commands/ # command line tools (./bin/gmg) + | |- themes/ # pre-bundled themes + | | + | | # ... some submodules here as well for different sections + | | # of the application... here's just a few + | |- auth/ # authentication (login/registration) code + | |- user_dev/ # user pages (under /u/), including media pages + | \- submit/ # submitting media for processing + | + |- docs/ # documentation + |- devtools/ # some scripts for developer convenience + | + |- user_dev/ # local instance sessions, media, etc + | + | # the below directories are installed into your virtualenv checkout + | + |- bin/ # scripts + |- develop-eggs/ + |- lib/ # python libraries installed into your virtualenv + |- include/ + |- mediagoblin.egg-info/ + \- parts/ + + +As you can see, all the code for GNU MediaGoblin is in the +``mediagoblin`` directory. + +Here are some interesting files and what they do: + +:routing.py: maps url paths to views +:views.py: views handle http requests +:forms.py: wtforms stuff for this submodule + +You'll notice that there are several sub-directories: tests, +templates, auth, submit, ... + +``tests`` holds the unit test code. + +``templates`` holds all the templates for the output. + +``auth`` and ``submit`` are modules that enacpsulate authentication +and media item submission. If you look in these directories, you'll +see they have their own ``routing.py``, ``view.py``, and forms.py in +addition to some other code. + +You'll also notice that mediagoblin/db/ contains quite a few things, +including the following: + +:models.py: This is where the database is set up +:mixin.py: Certain functions appended to models from here +:migrations.py: When creating a new migration (a change to the + database structure), we put it here + + Software Stack ============== @@ -111,73 +181,3 @@ Software Stack * `JQuery `_: for groovy JavaScript things - -What's where -============ - -After you've run checked out mediagoblin and followed the virtualenv -instantiation instructions, you're faced with the following directory -tree:: - - mediagoblin/ - |- mediagoblin/ # source code - | |- db/ # database setup - | |- tools/ # various utilities - | |- init/ # "initialization" tools (arguably should be in tools/) - | |- tests/ # unit tests - | |- templates/ # templates for this application - | |- media_types/ # code for processing, displaying different media - | |- storage/ # different storage backends - | |- gmg_commands/ # command line tools (./bin/gmg) - | |- themes/ # pre-bundled themes - | | - | | # ... some submodules here as well for different sections - | | # of the application... here's just a few - | |- auth/ # authentication (login/registration) code - | |- user_dev/ # user pages (under /u/), including media pages - | \- submit/ # submitting media for processing - | - |- docs/ # documentation - |- devtools/ # some scripts for developer convenience - | - |- user_dev/ # local instance sessions, media, etc - | - | # the below directories are installed into your virtualenv checkout - | - |- bin/ # scripts - |- develop-eggs/ - |- lib/ # python libraries installed into your virtualenv - |- include/ - |- mediagoblin.egg-info/ - \- parts/ - - -As you can see, all the code for GNU MediaGoblin is in the -``mediagoblin`` directory. - -Here are some interesting files and what they do: - -:routing.py: maps url paths to views -:views.py: views handle http requests -:forms.py: wtforms stuff for this submodule - -You'll notice that there are several sub-directories: tests, -templates, auth, submit, ... - -``tests`` holds the unit test code. - -``templates`` holds all the templates for the output. - -``auth`` and ``submit`` are modules that enacpsulate authentication -and media item submission. If you look in these directories, you'll -see they have their own ``routing.py``, ``view.py``, and forms.py in -addition to some other code. - -You'll also notice that mediagoblin/db/ contains quite a few things, -including the following: - -:models.py: This is where the database is set up -:mixin.py: Certain functions appended to models from here -:migrations.py: When creating a new migration (a change to the - database structure), we put it here - -- cgit v1.2.3 From 82a40cc4e145e4fdf5f81d7b6319cf713afa44c1 Mon Sep 17 00:00:00 2001 From: Elrond Date: Tue, 9 Apr 2013 22:39:04 +0200 Subject: Remove the last traces of beaker. There were still some traces of beaker around: - docs: replaced by reference to itsdangerous. - paste configs: Wiped away. - config_spec.ini: wiped. - test_mgoblin_app.ini: also wiped. --- docs/source/devel/codebase.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source/devel/codebase.rst') diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst index cd46242c..9718a097 100644 --- a/docs/source/devel/codebase.rst +++ b/docs/source/devel/codebase.rst @@ -142,8 +142,8 @@ Software Stack * `werkzeug `_: nice abstraction layer from HTTP requests, responses and WSGI bits - * `Beaker `_: for handling sessions and - caching + * `itsdangerous `_: + for handling sessions * `Jinja2 `_: the templating engine -- cgit v1.2.3 From 827f91e603bf706e628e8d2d625d49d79c62e721 Mon Sep 17 00:00:00 2001 From: Alon Levy Date: Wed, 17 Apr 2013 11:23:37 +0300 Subject: update documentation for s/nose/py.test/ Signed-off-by: Alon Levy --- docs/source/devel/codebase.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/devel/codebase.rst') diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst index 9718a097..122a3297 100644 --- a/docs/source/devel/codebase.rst +++ b/docs/source/devel/codebase.rst @@ -119,7 +119,7 @@ Software Stack * `Python `_: the language we're using to write this - * `Nose `_: + * `Py.Test `_: for unit tests * `virtualenv `_: for setting up an -- cgit v1.2.3