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 <http://mediagoblin.org/join/>`_
+ for where we hang out.
+
+For more information on how to get started hacking on GNU MediaGoblin,
+see :ref:`hacking-howto`.
+
Software Stack
==============
* `JQuery <http://jquery.com/>`_: for groovy JavaScript things
+
+What's where
+============
+
+After you've run buildout, you're faced with the following directory
+tree::
+
+ mediagoblin/
+ |- mediagoblin/ source code
+ | |- tests/
+ | |- templates/
+ | |- auth/
+ | \- submit/
+ |- docs/ documentation
+ |
+ | the rest of these directories are generated by
+ | buildout.
+ |
+ |- bin/ scripts
+ |- develop-eggs/
+ |- eggs/
+ |- 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 mongodb 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.
+
+
Recipes
=======
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ["mgext.youcanhelp"]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Contributing HOWTO
====================
+.. _join-the-community-section:
+
Join the community!
===================
We're super glad you want to join our community!
+See `the join page on the website <http://mediagoblin.org/join/>`_ for
+where we hang out.
+
There are a variety of ways you can help us and become part of the
team. We're not just looking for coders! We're also looking for
documentation writers, users, testers, evangelists, user-interface
=======================================
First thing to do is check out the `Web site
-<http://mediagoblin.org>`_ where we list all the project
+<http://mediagoblin.org/join/>`_ where we list all the project
infrastructure including:
-* the mailing list
* the IRC channel
-* the bug tracker
+* the mailing list
+* the issue tracker
Additionally, we have information on how to get involved, who to talk
to, what needs to be worked on, and other things besides!
+Second thing to do is take a look at :ref:`codebase-chapter` where
+we've started documenting how GNU MediaGoblin is built and how to add
+new things.
+
How to set up and maintain an environment for hacking
=====================================================
---------------------
While hacking on GNU MediaGoblin over time, you'll eventually have to
-update your development environment. To do that, run::
+update your development environment because the dependencies have
+changed. To do that, run::
./bin/buildout
+.. Note::
+
+ You only need to do this when dependencies are updated. You don't
+ need to do this when you've made code changes.
+
Wiping your environment for a clean-slate
-----------------------------------------
* parts/
* user_dev/
-FIXME - how to drop data from mongodb? we should probably write a
-script.
+
+.. YouCanHelp::
+
+ If you're familiar with MongoDB and bash, we'd love to get a bash
+ script that removes all the GNU MediaGoblin data from an existing
+ MongoDB instance. Let us know!
Running the server
./bin/nosetests
-What's where
-============
+Quickstart for Django programmers
+=================================
-After you've run buildout, you're faced with the following directory
-tree::
+We're not using Django, but the codebase is very Django-like in its
+structure.
- mediagoblin/
- |- mediagoblin/ source code
- | |- tests/
- | |- templates/
- | |- auth/
- | \- submit/
- |- docs/ documentation
- |
- | the rest of these directories are generated by
- | buildout.
- |
- |- bin/ scripts
- |- develop-eggs/
- |- eggs/
- |- mediagoblin.egg-info/
- |- parts/
- |- user_dev/ sessions, etc
+* ``routing.py`` is like ``urls.py`` in Django
+* ``models.py`` has mongokit ORM definitions
+* ``views.py`` is where the views go
+We're using MongoDB. Basically, instead of a relational database with
+tables, you have a big JSON structure which acts a lot like a Python
+dict.
-Quickstart for Django programmers
-=================================
+.. YouCanHelp::
-FIXME - write this
+ If there are other things that you think would help orient someone
+ new to GNU MediaGoblin but coming from Django, let us know!
Bite-sized bugs to start with
=============================
-FIXME - write this
+**May 3rd, 2011**: We don't have a list of bite-sized bugs, yet, but
+this is important to us. If you're interested in things to work on,
+let us know on `the mailing list <http://mediagoblin.org/join/>`_ or
+on the `IRC channel <http://mediagoblin.org/join/>`_.
Tips for people new to coding
These are all excellent texts.
-FIXME - are there good quality Python tutorial videos?
+.. YouCanHelp::
+
+ If you know of other good quality Python tutorials and Python
+ tutorial videos, let us know!
Learning Libraries GNU MediaGoblin uses
How can I participate?
======================
-See `Get Involved <http://mediagoblin.org/join/>`.
+See `Get Involved <http://mediagoblin.org/join/>`_ on the website..
How is GNU MediaGoblin licensed?
--- /dev/null
+from docutils import nodes
+
+from sphinx.util.compat import Directive, make_admonition
+
+class youcanhelp_node(nodes.Admonition, nodes.Element):
+ pass
+
+class YouCanHelp(Directive):
+ has_content = True
+ required_arguments = 0
+ optional_arguments = 0
+ final_argument_whitespace = False
+ option_spec = {}
+
+ def run(self):
+ ad = make_admonition(
+ youcanhelp_node,
+ self.name,
+ ["You Can Help!"],
+ self.options,
+ self.content,
+ self.lineno,
+ self.content_offset,
+ self.block_text,
+ self.state,
+ self.state_machine)
+ ad[0].line = self.lineno
+ return ad
+
+def visit_youcanhelp_node(self, node):
+ self.visit_admonition(node)
+
+def depart_youcanhelp_node(self, node):
+ self.depart_admonition(node)
+
+def setup(app):
+ app.add_node(
+ youcanhelp_node,
+ html=(visit_youcanhelp_node, depart_youcanhelp_node),
+ latex=(visit_youcanhelp_node, depart_youcanhelp_node),
+ text=(visit_youcanhelp_node, depart_youcanhelp_node)
+ )
+
+ app.add_directive('youcanhelp', YouCanHelp)
Theming HOWTO
===============
-FIXME - stub!
+We haven't implemented the necessary scaffolding to allow for theming
+yet. Thus, this chapter is a stub.
projects / mediagoblin.git / commitdiff