From d4535719370ca3be4790070e4bbe572671ba6045 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sat, 30 Jul 2011 16:25:44 -0400 Subject: 460. Adds texinfo output bits Building texinfo version of the manual only works with Sphinx from hg tip at present. Also, there are some minor issues and someone should go through the manual and read it to make sure there aren't issues. --- docs/Makefile | 21 +++++++++++++++++++++ docs/conf.py | 23 +++++++++++++++++++++++ 2 files changed, 44 insertions(+) (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index 81fc3d13..9a4608de 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,6 +12,9 @@ PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest help: @@ -113,6 +116,24 @@ man: @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo diff --git a/docs/conf.py b/docs/conf.py index 6c64cdda..a7acd3e2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -214,3 +214,26 @@ man_pages = [ ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', [u'Chris Webber, et al'], 1) ] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', u'gnumediagoblin', + 'GNU MediaGoblin', 'Media sharing web application.', 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' -- cgit v1.2.3 From 25a7eb25bf8ba7ce977434fda0d18be441fe3d07 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 31 Jul 2011 17:54:54 -0400 Subject: Moves docs files around so we build from source/ directory --- docs/Makefile | 12 +- docs/_static/placeholder | 0 docs/codebase.rst | 130 -------- docs/conf.py | 239 -------------- docs/contributinghowto.rst | 185 ----------- docs/deploymenthowto.rst | 16 - docs/designdecisions.rst | 329 -------------------- docs/foreword.rst | 46 --- docs/git.rst | 224 ------------- docs/goblin.png | Bin 47763 -> 0 bytes docs/hackinghowto.rst | 345 --------------------- docs/index.rst | 32 -- docs/mediagoblin.rst | 70 ----- docs/mgext/__init__.py | 0 docs/mgext/youcanhelp.py | 44 --- docs/snugglygoblin.png | Bin 163754 -> 0 bytes docs/source/_static/placeholder | 0 docs/source/_templates/mg_theme/layout.html | 39 +++ .../_templates/mg_theme/static/default.css_t | 299 ++++++++++++++++++ docs/source/_templates/mg_theme/theme.conf | 31 ++ docs/source/codebase.rst | 130 ++++++++ docs/source/conf.py | 239 ++++++++++++++ docs/source/contributinghowto.rst | 185 +++++++++++ docs/source/deploymenthowto.rst | 16 + docs/source/designdecisions.rst | 329 ++++++++++++++++++++ docs/source/foreword.rst | 46 +++ docs/source/git.rst | 224 +++++++++++++ docs/source/goblin.png | Bin 0 -> 47763 bytes docs/source/hackinghowto.rst | 345 +++++++++++++++++++++ docs/source/index.rst | 32 ++ docs/source/mediagoblin.rst | 70 +++++ docs/source/mgext/__init__.py | 0 docs/source/mgext/youcanhelp.py | 44 +++ docs/source/snugglygoblin.png | Bin 0 -> 163754 bytes docs/source/theminghowto.rst | 8 + docs/source/vision.rst | 142 +++++++++ docs/theminghowto.rst | 8 - docs/vision.rst | 142 --------- 38 files changed, 2186 insertions(+), 1815 deletions(-) delete mode 100644 docs/_static/placeholder delete mode 100644 docs/codebase.rst delete mode 100644 docs/conf.py delete mode 100644 docs/contributinghowto.rst delete mode 100644 docs/deploymenthowto.rst delete mode 100644 docs/designdecisions.rst delete mode 100644 docs/foreword.rst delete mode 100644 docs/git.rst delete mode 100644 docs/goblin.png delete mode 100644 docs/hackinghowto.rst delete mode 100644 docs/index.rst delete mode 100644 docs/mediagoblin.rst delete mode 100644 docs/mgext/__init__.py delete mode 100644 docs/mgext/youcanhelp.py delete mode 100644 docs/snugglygoblin.png create mode 100644 docs/source/_static/placeholder create mode 100644 docs/source/_templates/mg_theme/layout.html create mode 100644 docs/source/_templates/mg_theme/static/default.css_t create mode 100644 docs/source/_templates/mg_theme/theme.conf create mode 100644 docs/source/codebase.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/contributinghowto.rst create mode 100644 docs/source/deploymenthowto.rst create mode 100644 docs/source/designdecisions.rst create mode 100644 docs/source/foreword.rst create mode 100644 docs/source/git.rst create mode 100644 docs/source/goblin.png create mode 100644 docs/source/hackinghowto.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/mediagoblin.rst create mode 100644 docs/source/mgext/__init__.py create mode 100644 docs/source/mgext/youcanhelp.py create mode 100644 docs/source/snugglygoblin.png create mode 100644 docs/source/theminghowto.rst create mode 100644 docs/source/vision.rst delete mode 100644 docs/theminghowto.rst delete mode 100644 docs/vision.rst (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index 9a4608de..0b97bf7c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,17 +5,16 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = -BUILDDIR = _build +BUILDDIR = build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source # the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: @echo "Please use \`make ' where is one of" @@ -35,6 +34,9 @@ help: @echo " changes to make an overview of all changed/added/deprecated items" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" clean: -rm -rf $(BUILDDIR)/* diff --git a/docs/_static/placeholder b/docs/_static/placeholder deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/codebase.rst b/docs/codebase.rst deleted file mode 100644 index 898eadfe..00000000 --- a/docs/codebase.rst +++ /dev/null @@ -1,130 +0,0 @@ -.. _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 :ref:`hacking-howto`. - - -Software Stack -============== - -* Project infrastructure - - * `Python `_: the language we're using to write - this - - * `Nose `_: - for unit tests - - * `buildout `_: for getting dependencies, - building a runtime environment, ... - -* Data storage - - * `MongoDB `_: the document database backend - for storage - -* Web application - - * `Paste Deploy `_ and - `Paste Script `_: we'll use this for - configuring and launching the application - - * `WebOb `_: nice abstraction layer - from HTTP requests, responses and WSGI bits - - * `Routes `_: for URL routing - - * `Beaker `_: for handling sessions - - * `Jinja2 `_: the templating engine - - * `MongoKit `_: the lightweight - ORM for MongoDB we're using which will make it easier to define - structures and all that - - * `WTForms `_: for handling, - validation, and abstraction from HTML forms - - * `Celery `_: for task queuing (resizing - images, encoding video, ...) - - * `RabbitMQ `_: for sending tasks to celery - -* Front end - - * `JQuery `_: 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 below 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 -======= - -FIXME - write this diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index a7acd3e2..00000000 --- a/docs/conf.py +++ /dev/null @@ -1,239 +0,0 @@ -# -*- coding: utf-8 -*- -# -# GNU MediaGoblin documentation build configuration file, created by -# sphinx-quickstart on Thu Apr 7 20:10:27 2011. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# 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('.')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ["mgext.youcanhelp"] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'GNU MediaGoblin' -copyright = u'2011, Free Software Foundation, Inc and contributors' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.0.3' -# The full version, including alpha/beta/rc tags. -release = '0.0.3' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'default' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'GNUMediaGoblindoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'GNUMediaGoblin.tex', u'GNU MediaGoblin Documentation', - u'Chris Webber, et al', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', - [u'Chris Webber, et al'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', u'gnumediagoblin', - 'GNU MediaGoblin', 'Media sharing web application.', 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' diff --git a/docs/contributinghowto.rst b/docs/contributinghowto.rst deleted file mode 100644 index 06d2814e..00000000 --- a/docs/contributinghowto.rst +++ /dev/null @@ -1,185 +0,0 @@ -.. _contributing-howto-chapter: - -==================== - Contributing HOWTO -==================== - -.. contents:: Sections - :local: - - -.. _join-the-community-section: - -Join the community! -=================== - -We're super glad you want to join our community! - -See `the join page on the website `_ 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 -designers, graphics designers, user-experience designers, system -administrators, friends, painters, bakers, candle-stick makers... - -Here are some things you can do today: - - - **Hang out with us** - - You should hang out with us! We like people like you! - - At a bare minimum, join the `mailing list - `_ and say, "Hi!" - - We also hang out on IRC in ``#mediagoblin`` on Freenode.net. - - - **File bugs** - - Filing bugs is a critical part of any project. For more - information on filing bugs, see :ref:`filing-bugs`. - - - **Write/Fix some code** - - If you are a coder and you're looking to code, check out the - :ref:`hacking-howto`. We even have tips on *becoming* a coder - and we're willing to help you! - - - **Send encouragement** - - A nice word from you could send someone into a tizzy of - productive work. Ten nice words could complete a feature. - One hundred nice words could get us to the next milestone. - - Send it to the `mailing list `_ - or hop into ``#mediagoblin`` on Freenode.net and let us know. - - - **Spread the word** - - The seductive call of Free Software services is a powerful - one, but many cannot hear it because it's drowned out by the - rush hour traffic honking of proprietary walled gardens and - faux free services. Yuck! Be the sweet chirrup of the bird - amidst the din! Tell others that there is a better way to - live! - - FIXME - do we want to talk about ways to spread the word? - - FIXME - how can people notify us that they're spreading the - word? - - -We're still working on project infrastructure. We hope to have the -bits in place for these additional things to do in the coming months: - - **Become a user** - - We're building GNU MediaGoblin for us and for you but really - you're one of us and I am you and we are we and GNU - MediaGoblin is the walrus. - - Sign up for an account. Use the service. Relish in the - thought that this service comes with a heaping side of Freedom - and you can salt and pepper it to your liking. - - - **Help other users** - - Have you spent time with GNU MediaGoblin? If so, your - experience and wisdom are invaluable and you're the best - person we can think of to help other users with their - questions. - - - **Run your own instance** - - Are there things about our instance you want to change? Are - there things about other instances you wish were different? - Want to test upcoming changes? Want to create patches to - implement things you need? That's great---you can run your - own instance! - - For more information on deploying your own instance, see - :ref:`deployment-howto`. - - - **Translate GNU MediaGoblin** - - Knowing more than one language is an important skill. If you - are multi-lingual and are interested in translating GNU - MediaGoblin, see :ref:`translating`. - - - **Create a theme** - - As people deploy their own GNU MediaGoblin instances, good - themes are a must have! For more information on theming, see - :ref:`theming-howto`. - - -Contributing thank you drawings / copyright assignment -====================================================== - -Copyright assignment with GNU MediaGoblin to the `FSF -`_ is highly encouraged but not mandatory. To -incentivize both this and people to make cool contributions to our -project, if you make useful contributions to GNU MediaGoblin *and* do -a copyright assignment to the Free Software Foundation, the founder of -the project, Chris Webber, will make a custom drawing of a goblin -dedicated specifically to you. - -For why we're doing copyright assignment, see the -:ref:`design-decisions-chapter`. - - -.. _filing-bugs: - -File bugs -========= - -GNU MediaGoblin uses a bug tracker called `Redmine -`_. - -The bug tracker is at ``_. - -A good bug report has the following things in it: - -1. A short summary that's 60 characters or less. - -2. A description that describes the issue (bug, feature request, ...) - as well as the context. - - * If it's a bug, can you reproduce it? Is the issue specific to a - browser, computer, image, ...? - - * If it's a feature request, are there related links on the Internet - for more information? Would you be willing to help implement or - test the feature? - -That's it! When someone looks into the issue and has questions, -they'll contact you! - -If you don't hear from anyone in a couple of weeks, find someone on -IRC. - - -.. _translating: - -Translate GNU MediaGoblin -========================= - -Coming soon when we set up translation infrastructure. - - -Where to go when you get stuck -============================== - -Go to `our Web site `_ where we list the -various places we hang out and how to get a hold of us. - diff --git a/docs/deploymenthowto.rst b/docs/deploymenthowto.rst deleted file mode 100644 index f50edfb6..00000000 --- a/docs/deploymenthowto.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _deployment-howto: - -================== - Deployment HOWTO -================== - -Step 1: Write code that can be deployed. - -Step 2: ? - -Step 3: Write the deployment guide and profit! - -But seriously, this is a stub since we're not quite there (yet) but if -you want to see where we are now, you can try to run the latest -development version by following the instructions at -:ref:`hacking-howto`. diff --git a/docs/designdecisions.rst b/docs/designdecisions.rst deleted file mode 100644 index afa1e26b..00000000 --- a/docs/designdecisions.rst +++ /dev/null @@ -1,329 +0,0 @@ -.. _design-decisions-chapter: - -================== - Design Decisions -================== - -.. contents:: Sections - :local: - - -This chapter talks a bit about design decisions. - - -Why GNU MediaGoblin? -==================== - -Chris and Will on "Why GNU MediaGoblin": - - Chris came up with the name MediaGoblin. The name is pretty fun. - It merges the idea that this is a Media hosting project with - Goblin which sort of sounds like gobbling. Here's a piece of - software that gobbles up your media for all to see. - - `According to Wikipedia `_, a - goblin is: - - a legendary evil or mischievous illiterate creature, described - as grotesquely evil or evil-like phantom - - So are we evil? No. Are we mischievous or illiterate? Not - really. So what kind of goblin are we thinking about? We're - thinking about these goblins: - - .. figure:: goblin.png - :alt: Cute goblin with a beret. - - *Figure 1: Cute goblin with a beret. llustrated by Chris - Webber* - - .. figure:: snugglygoblin.png - :scale: 50% - :alt: Snuggly goblin with a beret. - - *Figure 2: Snuggly goblin. Illustrated by Karen Rustad* - - Those are pretty cute goblins. Those are the kinds of goblins - we're thinking about. - - Chris started doing work on the project after thinking about it - for a year. Then, after talking with Matt and Rob, it became an - official GNU project. Thus we now call it GNU MediaGoblin. - - That's a lot of letters, though, so in the interest of brevity and - facilitating easier casual conversation and balancing that with - what's important to us, we have the following rules: - - 1. "GNU MediaGoblin" is the name we're going to use in all official - capacities: web site, documentation, press releases, ... - - 2. In casual conversation, it's ok to use more casual names. - - 3. If you're writing about the project, we ask that you call it GNU - MediaGoblin. - - 4. If you don't like the name, we kindly ask you to take a deep - breath, think a happy thought about cute little goblins playing - on a playground and taking cute pictures of themselves, and let - it go. (Will added this one.) - - -Why Python -========== - -Chris Webber on "Why Python": - - Because I know Python, love Python, am capable of actually making - this thing happen in Python (I've worked on a lot of large free - software web applications before in Python, including `Miro - Community`_, the `Miro Guide`_, a large portion of `Creative - Commons`_, and a whole bunch of things while working at `Imaginary - Landscape`_). Me starting a project like this makes sense if it's - done in Python. - - You might say that PHP is way more deployable, that Rails has way - more cool developers riding around on fixie bikes---and all of - those things are true. But I know Python, like Python, and think - that Python is pretty great. I do think that deployment in Python - is not as good as with PHP, but I think the days of shared hosting - are (thankfully) coming to an end, and will probably be replaced - by cheap virtual machines spun up on the fly for people who want - that sort of stuff, and Python will be a huge part of that future, - maybe even more than PHP will. The deployment tools are getting - better. Maybe we can use something like Silver Lining. Maybe we - can just distribute as ``.debs`` or ``.rpms``. We'll figure it - out when we get there. - - Regardless, if I'm starting this project, which I am, it's gonna - be in Python. - -.. _Miro Community: http://mirocommunity.org/ -.. _Miro Guide: http://miroguide.org/ -.. _Creative Commons: http://creativecommons.org/ -.. _Imaginary Landscape: http://www.imagescape.com/ - - -Why WSGI Minimalism -=================== - -Chris Webber on "Why WSGI Minimalism": - - If you notice in the technology list I list a lot of components - that are very "django-like", but not actually `Django`_ - components. What can I say, I really like a lot of the ideas in - Django! Which leads to the question: why not just use Django? - - While I really like Django's ideas and a lot of its components, I - also feel that most of the best ideas in Django I want have been - implemented as good or even better outside of Django. I could - just use Django and replace the templating system with Jinja2, and - the form system with wtforms, and the database with MongoDB and - MongoKit, but at that point, how much of Django is really left? - - I also am sometimes saddened and irritated by how coupled all of - Django's components are. Loosely coupled yes, but still coupled. - WSGI has done a good job of providing a base layer for running - applications on and if you know how to do it yourself [1]_, it's - not hard or many lines of code at all to bind them together - without any framework at all (not even say `Pylons`_, `Pyramid`_ - or `Flask`_ which I think are still great projects, especially for - people who want this sort of thing but have no idea how to get - started). And even at this already really early stage of writing - MediaGoblin, that glue work is mostly done. - - Not to say I don't think Django isn't great for a lot of things. - For a lot of stuff, it's still the best, but not for MediaGoblin, - I think. - - One thing that Django does super well though is documentation. It - still has some faults, but even with those considered I can hardly - think of any other project in Python that has as nice of - documentation as Django. It may be worth learning some lessons on - documentation from Django [2]_, on that note. - - I'd really like to have a good, thorough hacking-howto and - deployment-howto, especially in the former making some notes on - how to make it easier for Django hackers to get started. - -.. _Django: http://www.djangoproject.com/ -.. _Pylons: http://pylonshq.com/ -.. _Pyramid: http://docs.pylonsproject.org/projects/pyramid/dev/ -.. _Flask: http://flask.pocoo.org/ - -.. [1] http://pythonpaste.org/webob/do-it-yourself.html -.. [2] http://pycon.blip.tv/file/4881071/ - - -Why MongoDB -=========== - -Chris Webber on "Why MongoDB": - - In case you were wondering, I am not a NOSQL fanboy, I do not go - around telling people that MongoDB is web scale. Actually my - choice for MongoDB isn't scalability, though scaling up really - nicely is a pretty good feature and sets us up well in case large - volume sites eventually do use MediaGoblin. But there's another - side of scalability, and that's scaling down, which is important - for federation, maybe even more important than scaling up in an - ideal universe where everyone ran servers out of their own - housing. As a memory-mapped database, MongoDB is pretty hungry, - so actually I spent a lot of time debating whether the inability - to scale down as nicely as something like SQL has with sqlite - meant that it was out. - - But I decided in the end that I really want MongoDB, not for - scalability, but for flexibility. Schema evolution pains in SQL - are almost enough reason for me to want MongoDB, but not quite. - The real reason is because I want the ability to eventually handle - multiple media types through MediaGoblin, and also allow for - plugins, without the rigidity of tables making that difficult. In - other words, something like:: - - {"title": "Me talking until you are bored", - "description": "blah blah blah", - "media_type": "audio", - "media_data": { - "length": "2:30", - "codec": "OGG Vorbis"}, - "plugin_data": { - "licensing": { - "license": "http://creativecommons.org/licenses/by-sa/3.0/"}}} - - - Being able to just dump media-specific information in a media_data - hashtable is pretty great, and even better is having a plugin - system where you can just let plugins have their own entire - key-value space cleanly inside the document that doesn't interfere - with anyone else's stuff. If we were to let plugins to deposit - their own information inside the database, either we'd let plugins - create their own tables which makes SQL migrations even harder - than they already are, or we'd probably end up creating a table - with a column for key, a column for value, and a column for type - in one huge table called "plugin_data" or something similar. (Yo - dawg, I heard you liked plugins, so I put a database in your - database so you can query while you query.) Gross. - - I also don't want things to be too loose so that we forget or lose - the structure of things, and that's one reason why I want to use - MongoKit, because we can cleanly define a much structure as we - want and verify that documents match that structure generally - without adding too much bloat or overhead (MongoKit is a pretty - lightweight wrapper and doesn't inject extra MongoKit-specific - stuff into the database, which is nice and nicer than many other - ORMs in that way). - - -Why Sphinx for documentation -============================ - -Will Kahn-Greene on "Why Sphinx": - - `Sphinx`_ is a fantastic tool for organizing documentation for a - Python-based project that makes it pretty easy to write docs that - are readable in source form and can be "compiled" into HTML, LaTeX - and other formats. - - There are other doc systems out there, but given that GNU - MediaGoblin is being written in Python and I've done a ton of - documentation using Sphinx, it makes sense to use Sphinx for now. - -.. _Sphinx: http://sphinx.pocoo.org/ - - -Why AGPLv3 and CC0? -=================== - -Chris, Brett, Will, Rob, Matt, et al curated into a story where -everyone is the hero by Will on "Why AGPLv3 and CC0": - - The `AGPL v3`_ preserves the freedoms guaranteed by the GPL v3 in - the context of software as a service. Using this license ensures - that users of the service have the ability to examine the source, - deploy their own instance, and implement their own version. This - is really important to us and a core mission component of this - project. Thus we decided that the software parts should be under - this license. - - However, the project is made up of more than just software: - there's CSS, images, and other output-related things. We wanted - the templates/images/css side of the project all permissive and - permissive in the same absolutely permissive way. We're waiving - our copyrights to non-software things under the CC0 waiver. - - That brings us to the templates where there's some code and some - output. The template engine we're using is called Jinja2. It - mixes HTML markup with Python code to render the output of the - software. We decided the templates are part of the output of the - software and not the software itself. We wanted the output of the - software to be licensed in a hassle-free way so that when someone - deploys their own GNU MediaGoblin instance with their own - templates, they don't have to deal with the copyleft aspects of - the AGPLv3 and we'd be fine with that because the changes they're - making are identity-related. So at first we decided to waive our - copyrights to the templates with a CC0 waiver and then add an - exception to the AGPLv3 for the software such that the templates - can make calls into the software and yet be a separately licensed - work. However, Brett brought up the question of whether this - allows some unscrupulous person to make changes to the software - through the templates in such a way that they're not bound by the - AGPLv3: i.e. a loophole. We thought about this loophole and - between this and the extra legalese involved in the exception to - the AGPLv3, we decided that it's just way simpler if the templates - were also licensed under the AGPLv3. - - Then we have the licensing for the documentation. Given that the - documentation is tied to the software content-wise, we don't feel - like we have to worry about ensuring freedom of the documentation - or worry about attribution concerns. Thus we're waiving our - copyrights to the documentation under CC0 as well. - - Lastly, we have branding. This covers logos and other things that - are distinctive to GNU MediaGoblin that we feel represents this - project. Since we don't currently have any branding, this is an - open issue, but we're thinking we'll go with a CC BY-SA license. - - By licensing in this way, we make sure that users of the software - receive the freedoms that the AGPLv3 ensures regardless of what - fate befalls this project. - - So to summarize: - - * software (Python, JavaScript, HTML templates): licensed - under AGPLv3 - * non-software things (CSS, images, video): copyrights waived - under CC0 because this is output of the software - * documentation: copyrights waived under CC0 because it's not part - of the software - * branding assets: we're kicking this can down the road, but - probably CC BY-SA - - This is all codified in the ``COPYING`` file. - -.. _AGPL v3: http://www.gnu.org/licenses/agpl.html -.. _CC0 v1: http://creativecommons.org/publicdomain/zero/1.0/ - - -Why (non-mandatory) copyright assignment? -========================================= - -Chris Webber on "Why copyright assignment?": - - GNU MediaGoblin is a GNU project with non-mandatory but heavily - encouraged copyright assignment to the FSF. Most, if not all, of - the core contributors to GNU MediaGoblin will have done a - copyright assignment, but unlike some other GNU projects, it isn't - required here. We think this is the best choice for GNU - MediaGoblin: it ensures that the Free Software Foundation may - protect the software by enforcing the AGPL if the FSF sees fit, - but it also means that we can immediately merge in changes from a - new contributor. It also means that some significant non-FSF - contributors might also be able to enforce the AGPL if seen fit. - - Again, assignment is not mandatory, but it is heavily encouraged, - even incentivized: significant contributors who do a copyright - assignment to the FSF are eligible to have a unique goblin drawing - produced for them by the project's main founder, Christopher Allan - Webber. See :ref:`contributing-howto-chapter` for details. - - diff --git a/docs/foreword.rst b/docs/foreword.rst deleted file mode 100644 index 1d423f08..00000000 --- a/docs/foreword.rst +++ /dev/null @@ -1,46 +0,0 @@ -========== - Foreword -========== - -About this manual -================= - -This is the GNU MediaGoblin manual. This documentation targets the -following groups of individuals: - -* people who want to use the software -* people who want to deploy the software -* contributors - -This manual is a living document and is in the ``mediagoblin`` -repository in the ``docs/`` directory. - - -Who wrote this documentation? -============================= - -In no particular order: - -* Chris -* Will -* Deb -* Greg -* Karen -* Matt -* Asheesh - - -I found an error in the docs---who do I tell? -============================================= - -There are a few ways---please pick the one most convenient to you! - -1. Write up a bug report in the bug tracker at http://bugs.foocorp.net/ . -2. Tell someone on IRC ``#mediagoblin`` on Freenode. -3. Send an email to Will ``willg at bluesock dot org``. - -When you tell us about your issue, please let us know: - -* where you are looking (in git? url of the web-page?) -* what the issue is -* your thoughts on how to resolve it diff --git a/docs/git.rst b/docs/git.rst deleted file mode 100644 index bd0f9d52..00000000 --- a/docs/git.rst +++ /dev/null @@ -1,224 +0,0 @@ -========================== - Git, Cloning and Patches -========================== - -.. contents:: Sections - :local: - - -GNU MediaGoblin uses git for all our version control and we have the -repositories hosted on `Gitorious `_. We have -two repositories: - -* MediaGoblin software: http://gitorious.org/mediagoblin/mediagoblin -* MediaGoblin website: http://gitorious.org/mediagoblin/mediagoblin-website - -It's most likely you want to look at the software repository--not the -website one. - -The rest of this chapter talks about using the software repository. - - -How to clone the project -======================== - -Do:: - - git clone git://gitorious.org/mediagoblin/mediagoblin.git - - -How to contribute changes -========================= - -Tie your changes to issues in the issue tracker ------------------------------------------------ - -All patches should be tied to issues in the `issue tracker -`_. That makes -it a lot easier for everyone to track proposed changes and make sure -your hard work doesn't get dropped on the floor! If there isn't an -issue for what you're working on, please create one. The better the -description of what it is you're trying to fix/implement, the better -everyone else is able to understand why you're doing what you're -doing. - - -Use bugfix branches to make changes ------------------------------------ - -The best way to isolate your changes is to create a branch based off -of the MediaGoblin repository master branch, do the changes related to -that one issue there, and then let us know how to get it. - -It's much easier on us if you isolate your changes to a branch focused -on the issue. Then we don't have to sift through things. - -It's much easier on you if you isolate your changes to a branch -focused on the issue. Then when we merge your changes in, you just -have to do a ``git fetch`` and that's it. This is especially true if -we reject some of your changes, but accept others or otherwise tweak -your changes. - -Further, if you isolate your changes to a branch, then you can work on -multiple issues at the same time and they don't conflict with one -another. - -Name your branches using the isue number and something that makes it clear -what it's about. For example, if you were working on tagging, you -might name your branch ``360_tagging``. - - -Properly document your changes ------------------------------- - -Include comments in the code. - -Write comprehensive commit messages. The better your commit message -is at describing what you did and why, the easier it is for us to -quickly accept your patch. - -Write comprehensive comments in the issue tracker about what you're -doing and why. - - -How to send us your changes ---------------------------- - -There are two ways to let us know how to get it: - -1. *(preferred)* **push changes to publicly available git clone and - let us know where to find it** - - Push your feature/bugfix/issue branch to your publicly available - git clone and add a comment to the issue with the url for your - clone and the branch to look at. - -2. **attaching the patch files to the issue** - - Run:: - - git format-patch --stdout /master > issue_.patch - - ``format-patch`` creates a patch of all the commits that are in - your branch that aren't in ``/master``. The ``--stdout`` - flag causes all this output to go to stdout where it's redirected - to a file named ``issue_.patch``. That file should be - based on the issue you're working with. For example, - ``issue_42.patch`` is a good filename and ``issue_42_rev2.patch`` - is good if you did a revision of it. - - Having said all that, the filename isn't wildly important. - - -Example workflow -================ - -Here's an example workflow. - - -Contributing changes --------------------- - -Slartibartfast from the planet Magrathea far off in the universe has -decided that he is bored with fjords and wants to fix issue 42 (the -meaning of life bug) and send us the changes. - -Slartibartfast has cloned the MediaGoblin repository and his clone -lives on gitorious. - -Slartibartfast works locally. The remote named ``origin`` points to -his clone on gitorious. The remote named ``gmg`` points to the -MediaGoblin repository. - -Slartibartfast does the following: - -1. Fetches the latest from the MediaGoblin repository:: - - git fetch --all -p - - This tells ``git fetch`` to fetch all the recent data from all of - the remotes (``--all``) and prune any branches that have been - deleted in the remotes (``-p``). - -2. Creates a branch from the tip of the MediaGoblin repository (the - remote is named ``gmg``) master branch called ``bug42_meaning_of_life``:: - - git checkout -b bug42_meaning_of_life gmg/master - - This creates a new branch (``-b``) named ``bug42_meaning_of_life`` based - on the tip of the ``master`` branch of the remote named ``gmg`` and checks - it out. - -3. Slartibartfast works hard on his changes in the ``bug42_meaning_of_life`` - branch. When done, he wants to notify us that he has made changes - he wants us to see. - -4. Slartibartfast pushes his changes to his clone:: - - git push origin bug42_meaning_of_life --set-upstream - - This pushes the changes in the ``bug42_meaning_of_life`` branch to the - remote named ``origin``. - -5. Slartibartfast adds a comment to issue 42 with the url for his - repository and the name of the branch he put the code in. He also - explains what he did and why it addresses the issue. - - -Updating a contribution ------------------------ - -Slartibartfast brushes his hands off with the sense of accomplishment -that comes with the knowledge of a job well done. He stands, wanders -over to get a cup of water, then realizes that he forgot to run the -unit tests! - -He runs the unit tests and discovers there's a bug in the code! - -Then he does this: - -1. He checks out the ``bug42_meaning_of_life`` branch:: - - git checkout bug42_meaning_of_life - -2. He fixes the bug and checks it into the ``bug42_meaning_of_life`` branch. - -3. He pushes his changes to his clone (the remote is named ``origin``):: - - git push origin bug42_meaning_of_life - -4. He adds another comment to issue 42 explaining about the mistake - and how he fixed it and that he's pushed the new change to the - ``bug42_meaning_of_life`` branch of his publicly available clone. - - -What happens next ------------------ - -Slartibartfast is once again happy with his work. He finds issue 42 -in the issue tracker and adds a comment saying he submitted a merge -request with his changes and explains what they are. - -Later, someone checks out his code and finds a problem with it. He -adds a comment to the issue tracker specifying the problem and asks -Slartibartfast to fix it. Slartibartfst goes through the above steps -again, fixes the issue, pushes it to his ``bug42_meaning_of_life`` branch and adds -another comment to the issue tracker about how he fixed it. - -Later, someone checks out his code and is happy with it. Someone -pulls it into the master branch of the MediaGoblin repository and adds -another comment to the issue and probably closes the issue out. - -Slartibartfast is notified of this. Slartibartfast does a:: - - git fetch --all - -The changes show up in the ``master`` branch of the ``gmg`` remote. -Slartibartfast now deletes his ``bug42_meaning_of_life`` branch -because he doesn't need it anymore. - - -How to learn git -================ - -Check out :ref:`hacking-howto-git`! diff --git a/docs/goblin.png b/docs/goblin.png deleted file mode 100644 index e20265e6..00000000 Binary files a/docs/goblin.png and /dev/null differ diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst deleted file mode 100644 index caafba53..00000000 --- a/docs/hackinghowto.rst +++ /dev/null @@ -1,345 +0,0 @@ -.. _hacking-howto: - -=============== - Hacking HOWTO -=============== - -.. contents:: Sections - :local: - - -So you want to hack on GNU MediaGoblin? -======================================= - -First thing to do is check out the `Web site -`_ where we list all the project -infrastructure including: - -* the IRC channel -* 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. - -Third you'll need to :ref:`get the requirements -`. - -Fourth, you'll need to build a development environment. We use buildout, -but if you want to use virtualenv, there's a set of mediocre not-very-supported -steps in the `wiki `_. - - -.. _get-requirements-section: - -Getting requirements -==================== - -First, you need to have the following installed before you can build -an environment for hacking on GNU MediaGoblin: - -* Python 2.6 or 2.7 - http://www.python.org/ - - You'll need Python as well as the dev files for building modules. - -* python-lxml - http://lxml.de/ -* git - http://git-scm.com/ -* MongoDB - http://www.mongodb.org/ - -If you're running Debian GNU/Linux or a Debian-derived distribution -such as Mint or Ubuntu, running the following should install these -requirements:: - - sudo apt-get install mongodb git-core python python-dev \ - python-lxml - -On Fedora:: - - yum install mongodb-server python-paste-deploy python-paste-script \ - git-core python python-devel python-lxml - -.. YouCanHelp:: - - If you have instructions for other GNU/Linux distributions to set - up requirements, let us know! - - -.. _hacking-with-buildout: - - -How to set up and maintain an environment for hacking with buildout -=================================================================== - -**Requirements** - -No additional requirements. - - -**Create a development environment** - -After installing the requirements, follow these steps: - -1. Clone the repository:: - - git clone git://gitorious.org/mediagoblin/mediagoblin.git - -2. Bootstrap and run buildout:: - - cd mediagoblin - python bootstrap.py && ./bin/buildout - - -That's it! Using this method, buildout should create a ``user_dev`` -directory, in which certain things will be stored (media, beaker -session stuff, etc). You can change this, but for development -purposes this default should be fine. - - -**Updating for dependency changes** - -While hacking on GNU MediaGoblin over time, you'll eventually have to -update your development environment because the dependencies have -changed. To do that, run:: - - ./bin/buildout && ./bin/gmg migrate - - -**Updating for code changes** - -You don't need to do anything---code changes are automatically -available. - - -**Deleting your buildout** - -At some point, you may want to delete your buildout. Perhaps it's to -start over. Perhaps it's to test building development environments -with buildout. - -To do this, do:: - - rm -rf bin develop-eggs eggs mediagoblin.egg-info parts user_dev - - -Running the server -================== - -If you want to get things running quickly and without hassle, just -run:: - - ./lazyserver.sh - -This will start up a python server where you can begin playing with -mediagoblin. It will also run celery in "always eager" mode so you -don't have to start a separate process for it. - -This is fine in development, but if you want to actually run celery -separately for testing (or deployment purposes), you'll want to run -the server independently:: - - ./bin/paster serve paste.ini --reload - - -Running celeryd -=============== - -If you aren't using ./lazyserver.sh or otherwise aren't running celery -in always eager mode, you'll need to do this if you want your media to -process and actually show up. It's probably a good idea in -development to have the web server (above) running in one terminal and -celeryd in another window. - -Run:: - - CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd - - -Running the test suite -====================== - -Run:: - - ./runtests.sh - - -Running a shell -=============== - -If you want a shell with your database pre-setup and an instantiated -application ready and at your fingertips.... - -Run:: - - ./bin/gmg shell - - -Troubleshooting -=============== - -pymongo.errors.AutoReconnect: could not find master/primary ------------------------------------------------------------ - -If you see this:: - - pymongo.errors.AutoReconnect: could not find master/primary - -then make sure mongodb is installed and running. - -If it's installed, check the mongodb log. On my machine, that's -``/var/log/mongodb/mongodb.log``. If you see something like:: - - old lock file: /var/lib/mongodb/mongod.lock. probably means... - -in that case you might have had an unclean shutdown. Try:: - - sudo mongod --repair - -If that didn't work, just delete the lock file and relaunch mongodb. - -Anyway, then start the mongodb server in whatever way is appropriate -for your distro / OS. - - -pkg_resources.DistributionNotFound: distribute ----------------------------------------------- - -If you get this while running buildout:: - - pkg_resources.DistributionNotFound: distribute - -Try this commmand instead:: - - python bootstrap.py --distribute && ./bin/buildout - - -Wiping your user data -===================== - -.. Note:: - - Unless you're doing development and working on and testing creating - a new instance, you will probably never have to do this. Will - plans to do this work and thus he documented it. - -.. YouCanHelp:: - - If you're familiar with MongoDB, we'd love to get a `script that - removes all the GNU MediaGoblin data from an existing instance - `_. Let us know! - - -Quickstart for Django programmers -================================= - -We're not using Django, but the codebase is very Django-like in its -structure. - -* ``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. - - -.. YouCanHelp:: - - 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 -============================= - -**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 `_ or -on the `IRC channel `_. - - -Tips for people new to coding -============================= - -Learning Python ---------------- - -GNU MediaGoblin is written using a programming language called `Python -`_. - -There are two different incompatible iterations of Python which I'll -refer to as Python 2 and Python 3. GNU MediaGoblin is written in -Python 2 and requires Python 2.6 or 2.7. At some point, we might -switch to Python 3, but that's a future thing. - -You can learn how to code in Python 2 from several excellent books -that are freely available on the Internet: - -* `Learn Python the Hard Way `_ -* `Dive Into Pyton `_ -* `Python for Software Design `_ -* `A Byte of Python `_ - -These are all excellent texts. - -.. YouCanHelp:: - - If you know of other good quality Python tutorials and Python - tutorial videos, let us know! - - -Learning Libraries GNU MediaGoblin uses ---------------------------------------- - -GNU MediaGoblin uses a variety of libraries in order to do what it -does. These libraries are listed in the :ref:`codebase-chapter` -along with links to the project Web sites and documentation for the -libraries. - -There are a variety of Python-related conferences every year that have -sessions covering many aspects of these libraries. You can find them -at `Python Miro Community `_ [0]_. - -.. [0] This is a shameless plug. Will Kahn-Greene runs Python Miro - Community. - -If you have questions or need help, find us on the mailing list and on -IRC. - - -.. _hacking-howto-git: - -Learning git ------------- - -git is an interesting and very powerful tool. Like all powerful -tools, it has a learning curve. - -If you're new to git, we highly recommend the following resources for -getting the hang of it: - -* `Learn Git `_ --- the GitHub - intro to git -* `Pro Git `_ --- fantastic book -* `Git casts `_ --- screencast covering git - usage -* `Git Reference `_ --- Git reference that makes - it easier to get the hang of git if you're coming from other version - control systems - -There's also a git mission at `OpenHatch `_. - - -Learning other utilities ------------------------- - -The `OpenHatch `_ site has a series of -`training missions `_ which are -designed to help you learn how to use these tools. - -If you're new to tar, diff, patch and git, we highly recommend you sign -up with OpenHatch and do the missions. diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 2f84d6a6..00000000 --- a/docs/index.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. GNU MediaGoblin documentation master file, created by - sphinx-quickstart on Thu Apr 7 20:10:27 2011. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to GNU MediaGoblin's documentation! -=========================================== - -Table of Contents: - -.. toctree:: - :maxdepth: 2 - - foreword - mediagoblin - contributinghowto - deploymenthowto - hackinghowto - theminghowto - git - codebase - designdecisions - vision - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/docs/mediagoblin.rst b/docs/mediagoblin.rst deleted file mode 100644 index c437ecc3..00000000 --- a/docs/mediagoblin.rst +++ /dev/null @@ -1,70 +0,0 @@ -================= - GNU MediaGoblin -================= - -.. contents:: Sections - :local: - - -What is GNU MediaGoblin -======================= - -Three years ago (2008), a number of free software luminaries got -together at the FSF office to answer the question, "What should -software freedom look like on the participatory web?" Those thinkers -included Richard Stallman---founder of the free software movement and -instigator of the GNU project, Evan Prodromou---the driving force -behind Status.net, a highly sucessful federated micro-blogging -service, and FIXME. - -Since that time Identi.ca and Libre.fm have answered the -freedom-loving web-user's need for micro-blogging and music sharing. -Now, GNU MediaGoblin is building a format for users to share photos. -Later versions of MediaGoblin will include support for video and other -media as well as tools to encourage collaboration on media projects. - - -Why are we doing this? -====================== - -Centralization and proprietization of media on the internet is a -serious problem and makes the web go from a system of extreme -resilience to a system of frightening fragility. We believe people -should be able to own their data and that means someone has to build -the tools to make it possible. We decided that in this case, that -someone would be us! - - -Who are you? -============ - -Free software activists and folks who have worked on a variety of -other projects like Libre.fm, GNU Social, Status.net, Miro, Miro -Community, OpenHatch and other projects as well. We're admirers and -contributors. We're writers and painters. We're friendly and -dedicated to computer user freedom. - - -How can I participate? -====================== - -See `Get Involved `_ on the website.. - - -How is GNU MediaGoblin licensed? -================================ - -GNU MediaGoblin software is released under an AGPLv3 license. - -See the ``COPYING`` file in the source for details. - - -Is this an official GNU Project? What does that mean? -====================================================== - -We are! It means that we meet the GNU Project's rigourous standards -for free software. To find out more about what that means, check out -`the GNU site `_. - -Please feel free to contact us with further questions! - diff --git a/docs/mgext/__init__.py b/docs/mgext/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/mgext/youcanhelp.py b/docs/mgext/youcanhelp.py deleted file mode 100644 index a99d0e4d..00000000 --- a/docs/mgext/youcanhelp.py +++ /dev/null @@ -1,44 +0,0 @@ -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) diff --git a/docs/snugglygoblin.png b/docs/snugglygoblin.png deleted file mode 100644 index f325ae4b..00000000 Binary files a/docs/snugglygoblin.png and /dev/null differ diff --git a/docs/source/_static/placeholder b/docs/source/_static/placeholder new file mode 100644 index 00000000..e69de29b diff --git a/docs/source/_templates/mg_theme/layout.html b/docs/source/_templates/mg_theme/layout.html new file mode 100644 index 00000000..eccda14b --- /dev/null +++ b/docs/source/_templates/mg_theme/layout.html @@ -0,0 +1,39 @@ +{# + default/layout.html + ~~~~~~~~~~~~~~~~~~~ + + Sphinx layout template for the default theme. + + :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +#} +{% extends "basic/layout.html" %} + +{% if theme_collapsiblesidebar|tobool %} +{% set script_files = script_files + ['_static/sidebar.js'] %} +{% endif %} + +{%- block footer %} +
+
+ {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- if last_updated %} + {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} + {%- endif %} + {% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.{% endtrans %} +
+Creative Commons License
{{ shorttitle|e }} by Will Kahn-Greene is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
+
+ + +{%- endblock %} diff --git a/docs/source/_templates/mg_theme/static/default.css_t b/docs/source/_templates/mg_theme/static/default.css_t new file mode 100644 index 00000000..f200a0fe --- /dev/null +++ b/docs/source/_templates/mg_theme/static/default.css_t @@ -0,0 +1,299 @@ +/* + * default.css_t + * ~~~~~~~~~~~~~ + * + * Sphinx stylesheet -- default theme. + * + * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: {{ theme_bodyfont }}; + font-size: 100%; + background-color: {{ theme_footerbgcolor }}; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + background-color: {{ theme_sidebarbgcolor }}; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.body { + background-color: {{ theme_bgcolor }}; + color: {{ theme_textcolor }}; + padding: 0 20px 30px 20px; +} + +{%- if theme_rightsidebar|tobool %} +div.bodywrapper { + margin: 0 230px 0 0; +} +{%- endif %} + +div.footer { + color: {{ theme_footertextcolor }}; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: {{ theme_footertextcolor }}; + text-decoration: underline; +} + +div.related { + background-color: {{ theme_relbarbgcolor }}; + line-height: 30px; + color: {{ theme_relbartextcolor }}; +} + +div.related a { + color: {{ theme_relbarlinkcolor }}; +} + +div.sphinxsidebar { + {%- if theme_stickysidebar|tobool %} + top: 30px; + bottom: 0; + margin: 0; + position: fixed; + overflow: auto; + height: auto; + {%- endif %} + {%- if theme_rightsidebar|tobool %} + float: right; + {%- if theme_stickysidebar|tobool %} + right: 0; + {%- endif %} + {%- endif %} +} + +{%- if theme_stickysidebar|tobool %} +/* this is nice, but it it leads to hidden headings when jumping + to an anchor */ +/* +div.related { + position: fixed; +} + +div.documentwrapper { + margin-top: 30px; +} +*/ +{%- endif %} + +div.sphinxsidebar h3 { + font-family: {{ theme_headfont }}; + color: {{ theme_sidebartextcolor }}; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: {{ theme_sidebartextcolor }}; +} + +div.sphinxsidebar h4 { + font-family: {{ theme_headfont }}; + color: {{ theme_sidebartextcolor }}; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: {{ theme_sidebartextcolor }}; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + color: {{ theme_sidebartextcolor }}; +} + +div.sphinxsidebar a { + color: {{ theme_sidebarlinkcolor }}; +} + +div.sphinxsidebar input { + border: 1px solid {{ theme_sidebarlinkcolor }}; + font-family: sans-serif; + font-size: 1em; +} + + +/* -- hyperlink styles ------------------------------------------------------ */ + +a { + color: {{ theme_linkcolor }}; + text-decoration: none; +} + +a:visited { + color: {{ theme_visitedlinkcolor }}; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +{% if theme_externalrefs|tobool %} +a.external { + text-decoration: none; + border-bottom: 1px dashed {{ theme_linkcolor }}; +} + +a.external:hover { + text-decoration: none; + border-bottom: none; +} +{% endif %} + +/* -- body styles ----------------------------------------------------------- */ + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: {{ theme_headfont }}; + background-color: {{ theme_headbgcolor }}; + font-weight: normal; + color: {{ theme_headtextcolor }}; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: {{ theme_headlinkcolor }}; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: {{ theme_headlinkcolor }}; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.admonition p { + margin-bottom: 5px; +} + +div.admonition pre { + margin-bottom: 5px; +} + +div.admonition ul, div.admonition ol { + margin-bottom: 5px; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + padding: 5px; + background-color: {{ theme_codebgcolor }}; + color: {{ theme_codetextcolor }}; + line-height: 120%; + border: 1px solid #ac9; + border-left: none; + border-right: none; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} + +th { + background-color: #ede; +} + +.warning tt { + background: #efc2c2; +} + +.note tt { + background: #d6d6d6; +} + +.viewcode-back { + font-family: {{ theme_bodyfont }}; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} diff --git a/docs/source/_templates/mg_theme/theme.conf b/docs/source/_templates/mg_theme/theme.conf new file mode 100644 index 00000000..49442e3b --- /dev/null +++ b/docs/source/_templates/mg_theme/theme.conf @@ -0,0 +1,31 @@ +[theme] +inherit = basic +stylesheet = default.css +pygments_style = sphinx + +[options] +rightsidebar = false +stickysidebar = false +collapsiblesidebar = false +externalrefs = false + +footerbgcolor = #b11818 +footertextcolor = #ffffff +sidebarbgcolor = #6a0000 +sidebartextcolor = #ffffff +sidebarlinkcolor = #98dbcc +relbarbgcolor = #b11818 +relbartextcolor = #ffffff +relbarlinkcolor = #ffffff +bgcolor = #ffffff +textcolor = #000000 +headbgcolor = #fdeded +headtextcolor = #20435c +headlinkcolor = #c60f0f +linkcolor = #355f7c +visitedlinkcolor = #355f7c +codebgcolor = #eeffcc +codetextcolor = #333333 + +bodyfont = sans-serif +headfont = 'Trebuchet MS', sans-serif diff --git a/docs/source/codebase.rst b/docs/source/codebase.rst new file mode 100644 index 00000000..898eadfe --- /dev/null +++ b/docs/source/codebase.rst @@ -0,0 +1,130 @@ +.. _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 :ref:`hacking-howto`. + + +Software Stack +============== + +* Project infrastructure + + * `Python `_: the language we're using to write + this + + * `Nose `_: + for unit tests + + * `buildout `_: for getting dependencies, + building a runtime environment, ... + +* Data storage + + * `MongoDB `_: the document database backend + for storage + +* Web application + + * `Paste Deploy `_ and + `Paste Script `_: we'll use this for + configuring and launching the application + + * `WebOb `_: nice abstraction layer + from HTTP requests, responses and WSGI bits + + * `Routes `_: for URL routing + + * `Beaker `_: for handling sessions + + * `Jinja2 `_: the templating engine + + * `MongoKit `_: the lightweight + ORM for MongoDB we're using which will make it easier to define + structures and all that + + * `WTForms `_: for handling, + validation, and abstraction from HTML forms + + * `Celery `_: for task queuing (resizing + images, encoding video, ...) + + * `RabbitMQ `_: for sending tasks to celery + +* Front end + + * `JQuery `_: 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 below 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 +======= + +FIXME - write this diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..5861a463 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,239 @@ +# -*- coding: utf-8 -*- +# +# GNU MediaGoblin documentation build configuration file, created by +# sphinx-quickstart on Thu Apr 7 20:10:27 2011. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# 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('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ["mgext.youcanhelp"] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'GNU MediaGoblin' +copyright = u'2011, Free Software Foundation, Inc and contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.0.3' +# The full version, including alpha/beta/rc tags. +release = '0.0.3' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build', 'mgext', '_templates', '_static'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'GNUMediaGoblindoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'GNUMediaGoblin.tex', u'GNU MediaGoblin Documentation', + u'Chris Webber, et al', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', + [u'Chris Webber, et al'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', u'gnumediagoblin', + 'GNU MediaGoblin', 'Media sharing web application.', 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' diff --git a/docs/source/contributinghowto.rst b/docs/source/contributinghowto.rst new file mode 100644 index 00000000..06d2814e --- /dev/null +++ b/docs/source/contributinghowto.rst @@ -0,0 +1,185 @@ +.. _contributing-howto-chapter: + +==================== + Contributing HOWTO +==================== + +.. contents:: Sections + :local: + + +.. _join-the-community-section: + +Join the community! +=================== + +We're super glad you want to join our community! + +See `the join page on the website `_ 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 +designers, graphics designers, user-experience designers, system +administrators, friends, painters, bakers, candle-stick makers... + +Here are some things you can do today: + + + **Hang out with us** + + You should hang out with us! We like people like you! + + At a bare minimum, join the `mailing list + `_ and say, "Hi!" + + We also hang out on IRC in ``#mediagoblin`` on Freenode.net. + + + **File bugs** + + Filing bugs is a critical part of any project. For more + information on filing bugs, see :ref:`filing-bugs`. + + + **Write/Fix some code** + + If you are a coder and you're looking to code, check out the + :ref:`hacking-howto`. We even have tips on *becoming* a coder + and we're willing to help you! + + + **Send encouragement** + + A nice word from you could send someone into a tizzy of + productive work. Ten nice words could complete a feature. + One hundred nice words could get us to the next milestone. + + Send it to the `mailing list `_ + or hop into ``#mediagoblin`` on Freenode.net and let us know. + + + **Spread the word** + + The seductive call of Free Software services is a powerful + one, but many cannot hear it because it's drowned out by the + rush hour traffic honking of proprietary walled gardens and + faux free services. Yuck! Be the sweet chirrup of the bird + amidst the din! Tell others that there is a better way to + live! + + FIXME - do we want to talk about ways to spread the word? + + FIXME - how can people notify us that they're spreading the + word? + + +We're still working on project infrastructure. We hope to have the +bits in place for these additional things to do in the coming months: + + **Become a user** + + We're building GNU MediaGoblin for us and for you but really + you're one of us and I am you and we are we and GNU + MediaGoblin is the walrus. + + Sign up for an account. Use the service. Relish in the + thought that this service comes with a heaping side of Freedom + and you can salt and pepper it to your liking. + + + **Help other users** + + Have you spent time with GNU MediaGoblin? If so, your + experience and wisdom are invaluable and you're the best + person we can think of to help other users with their + questions. + + + **Run your own instance** + + Are there things about our instance you want to change? Are + there things about other instances you wish were different? + Want to test upcoming changes? Want to create patches to + implement things you need? That's great---you can run your + own instance! + + For more information on deploying your own instance, see + :ref:`deployment-howto`. + + + **Translate GNU MediaGoblin** + + Knowing more than one language is an important skill. If you + are multi-lingual and are interested in translating GNU + MediaGoblin, see :ref:`translating`. + + + **Create a theme** + + As people deploy their own GNU MediaGoblin instances, good + themes are a must have! For more information on theming, see + :ref:`theming-howto`. + + +Contributing thank you drawings / copyright assignment +====================================================== + +Copyright assignment with GNU MediaGoblin to the `FSF +`_ is highly encouraged but not mandatory. To +incentivize both this and people to make cool contributions to our +project, if you make useful contributions to GNU MediaGoblin *and* do +a copyright assignment to the Free Software Foundation, the founder of +the project, Chris Webber, will make a custom drawing of a goblin +dedicated specifically to you. + +For why we're doing copyright assignment, see the +:ref:`design-decisions-chapter`. + + +.. _filing-bugs: + +File bugs +========= + +GNU MediaGoblin uses a bug tracker called `Redmine +`_. + +The bug tracker is at ``_. + +A good bug report has the following things in it: + +1. A short summary that's 60 characters or less. + +2. A description that describes the issue (bug, feature request, ...) + as well as the context. + + * If it's a bug, can you reproduce it? Is the issue specific to a + browser, computer, image, ...? + + * If it's a feature request, are there related links on the Internet + for more information? Would you be willing to help implement or + test the feature? + +That's it! When someone looks into the issue and has questions, +they'll contact you! + +If you don't hear from anyone in a couple of weeks, find someone on +IRC. + + +.. _translating: + +Translate GNU MediaGoblin +========================= + +Coming soon when we set up translation infrastructure. + + +Where to go when you get stuck +============================== + +Go to `our Web site `_ where we list the +various places we hang out and how to get a hold of us. + diff --git a/docs/source/deploymenthowto.rst b/docs/source/deploymenthowto.rst new file mode 100644 index 00000000..f50edfb6 --- /dev/null +++ b/docs/source/deploymenthowto.rst @@ -0,0 +1,16 @@ +.. _deployment-howto: + +================== + Deployment HOWTO +================== + +Step 1: Write code that can be deployed. + +Step 2: ? + +Step 3: Write the deployment guide and profit! + +But seriously, this is a stub since we're not quite there (yet) but if +you want to see where we are now, you can try to run the latest +development version by following the instructions at +:ref:`hacking-howto`. diff --git a/docs/source/designdecisions.rst b/docs/source/designdecisions.rst new file mode 100644 index 00000000..afa1e26b --- /dev/null +++ b/docs/source/designdecisions.rst @@ -0,0 +1,329 @@ +.. _design-decisions-chapter: + +================== + Design Decisions +================== + +.. contents:: Sections + :local: + + +This chapter talks a bit about design decisions. + + +Why GNU MediaGoblin? +==================== + +Chris and Will on "Why GNU MediaGoblin": + + Chris came up with the name MediaGoblin. The name is pretty fun. + It merges the idea that this is a Media hosting project with + Goblin which sort of sounds like gobbling. Here's a piece of + software that gobbles up your media for all to see. + + `According to Wikipedia `_, a + goblin is: + + a legendary evil or mischievous illiterate creature, described + as grotesquely evil or evil-like phantom + + So are we evil? No. Are we mischievous or illiterate? Not + really. So what kind of goblin are we thinking about? We're + thinking about these goblins: + + .. figure:: goblin.png + :alt: Cute goblin with a beret. + + *Figure 1: Cute goblin with a beret. llustrated by Chris + Webber* + + .. figure:: snugglygoblin.png + :scale: 50% + :alt: Snuggly goblin with a beret. + + *Figure 2: Snuggly goblin. Illustrated by Karen Rustad* + + Those are pretty cute goblins. Those are the kinds of goblins + we're thinking about. + + Chris started doing work on the project after thinking about it + for a year. Then, after talking with Matt and Rob, it became an + official GNU project. Thus we now call it GNU MediaGoblin. + + That's a lot of letters, though, so in the interest of brevity and + facilitating easier casual conversation and balancing that with + what's important to us, we have the following rules: + + 1. "GNU MediaGoblin" is the name we're going to use in all official + capacities: web site, documentation, press releases, ... + + 2. In casual conversation, it's ok to use more casual names. + + 3. If you're writing about the project, we ask that you call it GNU + MediaGoblin. + + 4. If you don't like the name, we kindly ask you to take a deep + breath, think a happy thought about cute little goblins playing + on a playground and taking cute pictures of themselves, and let + it go. (Will added this one.) + + +Why Python +========== + +Chris Webber on "Why Python": + + Because I know Python, love Python, am capable of actually making + this thing happen in Python (I've worked on a lot of large free + software web applications before in Python, including `Miro + Community`_, the `Miro Guide`_, a large portion of `Creative + Commons`_, and a whole bunch of things while working at `Imaginary + Landscape`_). Me starting a project like this makes sense if it's + done in Python. + + You might say that PHP is way more deployable, that Rails has way + more cool developers riding around on fixie bikes---and all of + those things are true. But I know Python, like Python, and think + that Python is pretty great. I do think that deployment in Python + is not as good as with PHP, but I think the days of shared hosting + are (thankfully) coming to an end, and will probably be replaced + by cheap virtual machines spun up on the fly for people who want + that sort of stuff, and Python will be a huge part of that future, + maybe even more than PHP will. The deployment tools are getting + better. Maybe we can use something like Silver Lining. Maybe we + can just distribute as ``.debs`` or ``.rpms``. We'll figure it + out when we get there. + + Regardless, if I'm starting this project, which I am, it's gonna + be in Python. + +.. _Miro Community: http://mirocommunity.org/ +.. _Miro Guide: http://miroguide.org/ +.. _Creative Commons: http://creativecommons.org/ +.. _Imaginary Landscape: http://www.imagescape.com/ + + +Why WSGI Minimalism +=================== + +Chris Webber on "Why WSGI Minimalism": + + If you notice in the technology list I list a lot of components + that are very "django-like", but not actually `Django`_ + components. What can I say, I really like a lot of the ideas in + Django! Which leads to the question: why not just use Django? + + While I really like Django's ideas and a lot of its components, I + also feel that most of the best ideas in Django I want have been + implemented as good or even better outside of Django. I could + just use Django and replace the templating system with Jinja2, and + the form system with wtforms, and the database with MongoDB and + MongoKit, but at that point, how much of Django is really left? + + I also am sometimes saddened and irritated by how coupled all of + Django's components are. Loosely coupled yes, but still coupled. + WSGI has done a good job of providing a base layer for running + applications on and if you know how to do it yourself [1]_, it's + not hard or many lines of code at all to bind them together + without any framework at all (not even say `Pylons`_, `Pyramid`_ + or `Flask`_ which I think are still great projects, especially for + people who want this sort of thing but have no idea how to get + started). And even at this already really early stage of writing + MediaGoblin, that glue work is mostly done. + + Not to say I don't think Django isn't great for a lot of things. + For a lot of stuff, it's still the best, but not for MediaGoblin, + I think. + + One thing that Django does super well though is documentation. It + still has some faults, but even with those considered I can hardly + think of any other project in Python that has as nice of + documentation as Django. It may be worth learning some lessons on + documentation from Django [2]_, on that note. + + I'd really like to have a good, thorough hacking-howto and + deployment-howto, especially in the former making some notes on + how to make it easier for Django hackers to get started. + +.. _Django: http://www.djangoproject.com/ +.. _Pylons: http://pylonshq.com/ +.. _Pyramid: http://docs.pylonsproject.org/projects/pyramid/dev/ +.. _Flask: http://flask.pocoo.org/ + +.. [1] http://pythonpaste.org/webob/do-it-yourself.html +.. [2] http://pycon.blip.tv/file/4881071/ + + +Why MongoDB +=========== + +Chris Webber on "Why MongoDB": + + In case you were wondering, I am not a NOSQL fanboy, I do not go + around telling people that MongoDB is web scale. Actually my + choice for MongoDB isn't scalability, though scaling up really + nicely is a pretty good feature and sets us up well in case large + volume sites eventually do use MediaGoblin. But there's another + side of scalability, and that's scaling down, which is important + for federation, maybe even more important than scaling up in an + ideal universe where everyone ran servers out of their own + housing. As a memory-mapped database, MongoDB is pretty hungry, + so actually I spent a lot of time debating whether the inability + to scale down as nicely as something like SQL has with sqlite + meant that it was out. + + But I decided in the end that I really want MongoDB, not for + scalability, but for flexibility. Schema evolution pains in SQL + are almost enough reason for me to want MongoDB, but not quite. + The real reason is because I want the ability to eventually handle + multiple media types through MediaGoblin, and also allow for + plugins, without the rigidity of tables making that difficult. In + other words, something like:: + + {"title": "Me talking until you are bored", + "description": "blah blah blah", + "media_type": "audio", + "media_data": { + "length": "2:30", + "codec": "OGG Vorbis"}, + "plugin_data": { + "licensing": { + "license": "http://creativecommons.org/licenses/by-sa/3.0/"}}} + + + Being able to just dump media-specific information in a media_data + hashtable is pretty great, and even better is having a plugin + system where you can just let plugins have their own entire + key-value space cleanly inside the document that doesn't interfere + with anyone else's stuff. If we were to let plugins to deposit + their own information inside the database, either we'd let plugins + create their own tables which makes SQL migrations even harder + than they already are, or we'd probably end up creating a table + with a column for key, a column for value, and a column for type + in one huge table called "plugin_data" or something similar. (Yo + dawg, I heard you liked plugins, so I put a database in your + database so you can query while you query.) Gross. + + I also don't want things to be too loose so that we forget or lose + the structure of things, and that's one reason why I want to use + MongoKit, because we can cleanly define a much structure as we + want and verify that documents match that structure generally + without adding too much bloat or overhead (MongoKit is a pretty + lightweight wrapper and doesn't inject extra MongoKit-specific + stuff into the database, which is nice and nicer than many other + ORMs in that way). + + +Why Sphinx for documentation +============================ + +Will Kahn-Greene on "Why Sphinx": + + `Sphinx`_ is a fantastic tool for organizing documentation for a + Python-based project that makes it pretty easy to write docs that + are readable in source form and can be "compiled" into HTML, LaTeX + and other formats. + + There are other doc systems out there, but given that GNU + MediaGoblin is being written in Python and I've done a ton of + documentation using Sphinx, it makes sense to use Sphinx for now. + +.. _Sphinx: http://sphinx.pocoo.org/ + + +Why AGPLv3 and CC0? +=================== + +Chris, Brett, Will, Rob, Matt, et al curated into a story where +everyone is the hero by Will on "Why AGPLv3 and CC0": + + The `AGPL v3`_ preserves the freedoms guaranteed by the GPL v3 in + the context of software as a service. Using this license ensures + that users of the service have the ability to examine the source, + deploy their own instance, and implement their own version. This + is really important to us and a core mission component of this + project. Thus we decided that the software parts should be under + this license. + + However, the project is made up of more than just software: + there's CSS, images, and other output-related things. We wanted + the templates/images/css side of the project all permissive and + permissive in the same absolutely permissive way. We're waiving + our copyrights to non-software things under the CC0 waiver. + + That brings us to the templates where there's some code and some + output. The template engine we're using is called Jinja2. It + mixes HTML markup with Python code to render the output of the + software. We decided the templates are part of the output of the + software and not the software itself. We wanted the output of the + software to be licensed in a hassle-free way so that when someone + deploys their own GNU MediaGoblin instance with their own + templates, they don't have to deal with the copyleft aspects of + the AGPLv3 and we'd be fine with that because the changes they're + making are identity-related. So at first we decided to waive our + copyrights to the templates with a CC0 waiver and then add an + exception to the AGPLv3 for the software such that the templates + can make calls into the software and yet be a separately licensed + work. However, Brett brought up the question of whether this + allows some unscrupulous person to make changes to the software + through the templates in such a way that they're not bound by the + AGPLv3: i.e. a loophole. We thought about this loophole and + between this and the extra legalese involved in the exception to + the AGPLv3, we decided that it's just way simpler if the templates + were also licensed under the AGPLv3. + + Then we have the licensing for the documentation. Given that the + documentation is tied to the software content-wise, we don't feel + like we have to worry about ensuring freedom of the documentation + or worry about attribution concerns. Thus we're waiving our + copyrights to the documentation under CC0 as well. + + Lastly, we have branding. This covers logos and other things that + are distinctive to GNU MediaGoblin that we feel represents this + project. Since we don't currently have any branding, this is an + open issue, but we're thinking we'll go with a CC BY-SA license. + + By licensing in this way, we make sure that users of the software + receive the freedoms that the AGPLv3 ensures regardless of what + fate befalls this project. + + So to summarize: + + * software (Python, JavaScript, HTML templates): licensed + under AGPLv3 + * non-software things (CSS, images, video): copyrights waived + under CC0 because this is output of the software + * documentation: copyrights waived under CC0 because it's not part + of the software + * branding assets: we're kicking this can down the road, but + probably CC BY-SA + + This is all codified in the ``COPYING`` file. + +.. _AGPL v3: http://www.gnu.org/licenses/agpl.html +.. _CC0 v1: http://creativecommons.org/publicdomain/zero/1.0/ + + +Why (non-mandatory) copyright assignment? +========================================= + +Chris Webber on "Why copyright assignment?": + + GNU MediaGoblin is a GNU project with non-mandatory but heavily + encouraged copyright assignment to the FSF. Most, if not all, of + the core contributors to GNU MediaGoblin will have done a + copyright assignment, but unlike some other GNU projects, it isn't + required here. We think this is the best choice for GNU + MediaGoblin: it ensures that the Free Software Foundation may + protect the software by enforcing the AGPL if the FSF sees fit, + but it also means that we can immediately merge in changes from a + new contributor. It also means that some significant non-FSF + contributors might also be able to enforce the AGPL if seen fit. + + Again, assignment is not mandatory, but it is heavily encouraged, + even incentivized: significant contributors who do a copyright + assignment to the FSF are eligible to have a unique goblin drawing + produced for them by the project's main founder, Christopher Allan + Webber. See :ref:`contributing-howto-chapter` for details. + + diff --git a/docs/source/foreword.rst b/docs/source/foreword.rst new file mode 100644 index 00000000..1d423f08 --- /dev/null +++ b/docs/source/foreword.rst @@ -0,0 +1,46 @@ +========== + Foreword +========== + +About this manual +================= + +This is the GNU MediaGoblin manual. This documentation targets the +following groups of individuals: + +* people who want to use the software +* people who want to deploy the software +* contributors + +This manual is a living document and is in the ``mediagoblin`` +repository in the ``docs/`` directory. + + +Who wrote this documentation? +============================= + +In no particular order: + +* Chris +* Will +* Deb +* Greg +* Karen +* Matt +* Asheesh + + +I found an error in the docs---who do I tell? +============================================= + +There are a few ways---please pick the one most convenient to you! + +1. Write up a bug report in the bug tracker at http://bugs.foocorp.net/ . +2. Tell someone on IRC ``#mediagoblin`` on Freenode. +3. Send an email to Will ``willg at bluesock dot org``. + +When you tell us about your issue, please let us know: + +* where you are looking (in git? url of the web-page?) +* what the issue is +* your thoughts on how to resolve it diff --git a/docs/source/git.rst b/docs/source/git.rst new file mode 100644 index 00000000..bd0f9d52 --- /dev/null +++ b/docs/source/git.rst @@ -0,0 +1,224 @@ +========================== + Git, Cloning and Patches +========================== + +.. contents:: Sections + :local: + + +GNU MediaGoblin uses git for all our version control and we have the +repositories hosted on `Gitorious `_. We have +two repositories: + +* MediaGoblin software: http://gitorious.org/mediagoblin/mediagoblin +* MediaGoblin website: http://gitorious.org/mediagoblin/mediagoblin-website + +It's most likely you want to look at the software repository--not the +website one. + +The rest of this chapter talks about using the software repository. + + +How to clone the project +======================== + +Do:: + + git clone git://gitorious.org/mediagoblin/mediagoblin.git + + +How to contribute changes +========================= + +Tie your changes to issues in the issue tracker +----------------------------------------------- + +All patches should be tied to issues in the `issue tracker +`_. That makes +it a lot easier for everyone to track proposed changes and make sure +your hard work doesn't get dropped on the floor! If there isn't an +issue for what you're working on, please create one. The better the +description of what it is you're trying to fix/implement, the better +everyone else is able to understand why you're doing what you're +doing. + + +Use bugfix branches to make changes +----------------------------------- + +The best way to isolate your changes is to create a branch based off +of the MediaGoblin repository master branch, do the changes related to +that one issue there, and then let us know how to get it. + +It's much easier on us if you isolate your changes to a branch focused +on the issue. Then we don't have to sift through things. + +It's much easier on you if you isolate your changes to a branch +focused on the issue. Then when we merge your changes in, you just +have to do a ``git fetch`` and that's it. This is especially true if +we reject some of your changes, but accept others or otherwise tweak +your changes. + +Further, if you isolate your changes to a branch, then you can work on +multiple issues at the same time and they don't conflict with one +another. + +Name your branches using the isue number and something that makes it clear +what it's about. For example, if you were working on tagging, you +might name your branch ``360_tagging``. + + +Properly document your changes +------------------------------ + +Include comments in the code. + +Write comprehensive commit messages. The better your commit message +is at describing what you did and why, the easier it is for us to +quickly accept your patch. + +Write comprehensive comments in the issue tracker about what you're +doing and why. + + +How to send us your changes +--------------------------- + +There are two ways to let us know how to get it: + +1. *(preferred)* **push changes to publicly available git clone and + let us know where to find it** + + Push your feature/bugfix/issue branch to your publicly available + git clone and add a comment to the issue with the url for your + clone and the branch to look at. + +2. **attaching the patch files to the issue** + + Run:: + + git format-patch --stdout /master > issue_.patch + + ``format-patch`` creates a patch of all the commits that are in + your branch that aren't in ``/master``. The ``--stdout`` + flag causes all this output to go to stdout where it's redirected + to a file named ``issue_.patch``. That file should be + based on the issue you're working with. For example, + ``issue_42.patch`` is a good filename and ``issue_42_rev2.patch`` + is good if you did a revision of it. + + Having said all that, the filename isn't wildly important. + + +Example workflow +================ + +Here's an example workflow. + + +Contributing changes +-------------------- + +Slartibartfast from the planet Magrathea far off in the universe has +decided that he is bored with fjords and wants to fix issue 42 (the +meaning of life bug) and send us the changes. + +Slartibartfast has cloned the MediaGoblin repository and his clone +lives on gitorious. + +Slartibartfast works locally. The remote named ``origin`` points to +his clone on gitorious. The remote named ``gmg`` points to the +MediaGoblin repository. + +Slartibartfast does the following: + +1. Fetches the latest from the MediaGoblin repository:: + + git fetch --all -p + + This tells ``git fetch`` to fetch all the recent data from all of + the remotes (``--all``) and prune any branches that have been + deleted in the remotes (``-p``). + +2. Creates a branch from the tip of the MediaGoblin repository (the + remote is named ``gmg``) master branch called ``bug42_meaning_of_life``:: + + git checkout -b bug42_meaning_of_life gmg/master + + This creates a new branch (``-b``) named ``bug42_meaning_of_life`` based + on the tip of the ``master`` branch of the remote named ``gmg`` and checks + it out. + +3. Slartibartfast works hard on his changes in the ``bug42_meaning_of_life`` + branch. When done, he wants to notify us that he has made changes + he wants us to see. + +4. Slartibartfast pushes his changes to his clone:: + + git push origin bug42_meaning_of_life --set-upstream + + This pushes the changes in the ``bug42_meaning_of_life`` branch to the + remote named ``origin``. + +5. Slartibartfast adds a comment to issue 42 with the url for his + repository and the name of the branch he put the code in. He also + explains what he did and why it addresses the issue. + + +Updating a contribution +----------------------- + +Slartibartfast brushes his hands off with the sense of accomplishment +that comes with the knowledge of a job well done. He stands, wanders +over to get a cup of water, then realizes that he forgot to run the +unit tests! + +He runs the unit tests and discovers there's a bug in the code! + +Then he does this: + +1. He checks out the ``bug42_meaning_of_life`` branch:: + + git checkout bug42_meaning_of_life + +2. He fixes the bug and checks it into the ``bug42_meaning_of_life`` branch. + +3. He pushes his changes to his clone (the remote is named ``origin``):: + + git push origin bug42_meaning_of_life + +4. He adds another comment to issue 42 explaining about the mistake + and how he fixed it and that he's pushed the new change to the + ``bug42_meaning_of_life`` branch of his publicly available clone. + + +What happens next +----------------- + +Slartibartfast is once again happy with his work. He finds issue 42 +in the issue tracker and adds a comment saying he submitted a merge +request with his changes and explains what they are. + +Later, someone checks out his code and finds a problem with it. He +adds a comment to the issue tracker specifying the problem and asks +Slartibartfast to fix it. Slartibartfst goes through the above steps +again, fixes the issue, pushes it to his ``bug42_meaning_of_life`` branch and adds +another comment to the issue tracker about how he fixed it. + +Later, someone checks out his code and is happy with it. Someone +pulls it into the master branch of the MediaGoblin repository and adds +another comment to the issue and probably closes the issue out. + +Slartibartfast is notified of this. Slartibartfast does a:: + + git fetch --all + +The changes show up in the ``master`` branch of the ``gmg`` remote. +Slartibartfast now deletes his ``bug42_meaning_of_life`` branch +because he doesn't need it anymore. + + +How to learn git +================ + +Check out :ref:`hacking-howto-git`! diff --git a/docs/source/goblin.png b/docs/source/goblin.png new file mode 100644 index 00000000..e20265e6 Binary files /dev/null and b/docs/source/goblin.png differ diff --git a/docs/source/hackinghowto.rst b/docs/source/hackinghowto.rst new file mode 100644 index 00000000..caafba53 --- /dev/null +++ b/docs/source/hackinghowto.rst @@ -0,0 +1,345 @@ +.. _hacking-howto: + +=============== + Hacking HOWTO +=============== + +.. contents:: Sections + :local: + + +So you want to hack on GNU MediaGoblin? +======================================= + +First thing to do is check out the `Web site +`_ where we list all the project +infrastructure including: + +* the IRC channel +* 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. + +Third you'll need to :ref:`get the requirements +`. + +Fourth, you'll need to build a development environment. We use buildout, +but if you want to use virtualenv, there's a set of mediocre not-very-supported +steps in the `wiki `_. + + +.. _get-requirements-section: + +Getting requirements +==================== + +First, you need to have the following installed before you can build +an environment for hacking on GNU MediaGoblin: + +* Python 2.6 or 2.7 - http://www.python.org/ + + You'll need Python as well as the dev files for building modules. + +* python-lxml - http://lxml.de/ +* git - http://git-scm.com/ +* MongoDB - http://www.mongodb.org/ + +If you're running Debian GNU/Linux or a Debian-derived distribution +such as Mint or Ubuntu, running the following should install these +requirements:: + + sudo apt-get install mongodb git-core python python-dev \ + python-lxml + +On Fedora:: + + yum install mongodb-server python-paste-deploy python-paste-script \ + git-core python python-devel python-lxml + +.. YouCanHelp:: + + If you have instructions for other GNU/Linux distributions to set + up requirements, let us know! + + +.. _hacking-with-buildout: + + +How to set up and maintain an environment for hacking with buildout +=================================================================== + +**Requirements** + +No additional requirements. + + +**Create a development environment** + +After installing the requirements, follow these steps: + +1. Clone the repository:: + + git clone git://gitorious.org/mediagoblin/mediagoblin.git + +2. Bootstrap and run buildout:: + + cd mediagoblin + python bootstrap.py && ./bin/buildout + + +That's it! Using this method, buildout should create a ``user_dev`` +directory, in which certain things will be stored (media, beaker +session stuff, etc). You can change this, but for development +purposes this default should be fine. + + +**Updating for dependency changes** + +While hacking on GNU MediaGoblin over time, you'll eventually have to +update your development environment because the dependencies have +changed. To do that, run:: + + ./bin/buildout && ./bin/gmg migrate + + +**Updating for code changes** + +You don't need to do anything---code changes are automatically +available. + + +**Deleting your buildout** + +At some point, you may want to delete your buildout. Perhaps it's to +start over. Perhaps it's to test building development environments +with buildout. + +To do this, do:: + + rm -rf bin develop-eggs eggs mediagoblin.egg-info parts user_dev + + +Running the server +================== + +If you want to get things running quickly and without hassle, just +run:: + + ./lazyserver.sh + +This will start up a python server where you can begin playing with +mediagoblin. It will also run celery in "always eager" mode so you +don't have to start a separate process for it. + +This is fine in development, but if you want to actually run celery +separately for testing (or deployment purposes), you'll want to run +the server independently:: + + ./bin/paster serve paste.ini --reload + + +Running celeryd +=============== + +If you aren't using ./lazyserver.sh or otherwise aren't running celery +in always eager mode, you'll need to do this if you want your media to +process and actually show up. It's probably a good idea in +development to have the web server (above) running in one terminal and +celeryd in another window. + +Run:: + + CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd + + +Running the test suite +====================== + +Run:: + + ./runtests.sh + + +Running a shell +=============== + +If you want a shell with your database pre-setup and an instantiated +application ready and at your fingertips.... + +Run:: + + ./bin/gmg shell + + +Troubleshooting +=============== + +pymongo.errors.AutoReconnect: could not find master/primary +----------------------------------------------------------- + +If you see this:: + + pymongo.errors.AutoReconnect: could not find master/primary + +then make sure mongodb is installed and running. + +If it's installed, check the mongodb log. On my machine, that's +``/var/log/mongodb/mongodb.log``. If you see something like:: + + old lock file: /var/lib/mongodb/mongod.lock. probably means... + +in that case you might have had an unclean shutdown. Try:: + + sudo mongod --repair + +If that didn't work, just delete the lock file and relaunch mongodb. + +Anyway, then start the mongodb server in whatever way is appropriate +for your distro / OS. + + +pkg_resources.DistributionNotFound: distribute +---------------------------------------------- + +If you get this while running buildout:: + + pkg_resources.DistributionNotFound: distribute + +Try this commmand instead:: + + python bootstrap.py --distribute && ./bin/buildout + + +Wiping your user data +===================== + +.. Note:: + + Unless you're doing development and working on and testing creating + a new instance, you will probably never have to do this. Will + plans to do this work and thus he documented it. + +.. YouCanHelp:: + + If you're familiar with MongoDB, we'd love to get a `script that + removes all the GNU MediaGoblin data from an existing instance + `_. Let us know! + + +Quickstart for Django programmers +================================= + +We're not using Django, but the codebase is very Django-like in its +structure. + +* ``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. + + +.. YouCanHelp:: + + 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 +============================= + +**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 `_ or +on the `IRC channel `_. + + +Tips for people new to coding +============================= + +Learning Python +--------------- + +GNU MediaGoblin is written using a programming language called `Python +`_. + +There are two different incompatible iterations of Python which I'll +refer to as Python 2 and Python 3. GNU MediaGoblin is written in +Python 2 and requires Python 2.6 or 2.7. At some point, we might +switch to Python 3, but that's a future thing. + +You can learn how to code in Python 2 from several excellent books +that are freely available on the Internet: + +* `Learn Python the Hard Way `_ +* `Dive Into Pyton `_ +* `Python for Software Design `_ +* `A Byte of Python `_ + +These are all excellent texts. + +.. YouCanHelp:: + + If you know of other good quality Python tutorials and Python + tutorial videos, let us know! + + +Learning Libraries GNU MediaGoblin uses +--------------------------------------- + +GNU MediaGoblin uses a variety of libraries in order to do what it +does. These libraries are listed in the :ref:`codebase-chapter` +along with links to the project Web sites and documentation for the +libraries. + +There are a variety of Python-related conferences every year that have +sessions covering many aspects of these libraries. You can find them +at `Python Miro Community `_ [0]_. + +.. [0] This is a shameless plug. Will Kahn-Greene runs Python Miro + Community. + +If you have questions or need help, find us on the mailing list and on +IRC. + + +.. _hacking-howto-git: + +Learning git +------------ + +git is an interesting and very powerful tool. Like all powerful +tools, it has a learning curve. + +If you're new to git, we highly recommend the following resources for +getting the hang of it: + +* `Learn Git `_ --- the GitHub + intro to git +* `Pro Git `_ --- fantastic book +* `Git casts `_ --- screencast covering git + usage +* `Git Reference `_ --- Git reference that makes + it easier to get the hang of git if you're coming from other version + control systems + +There's also a git mission at `OpenHatch `_. + + +Learning other utilities +------------------------ + +The `OpenHatch `_ site has a series of +`training missions `_ which are +designed to help you learn how to use these tools. + +If you're new to tar, diff, patch and git, we highly recommend you sign +up with OpenHatch and do the missions. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..2f84d6a6 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,32 @@ +.. GNU MediaGoblin documentation master file, created by + sphinx-quickstart on Thu Apr 7 20:10:27 2011. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to GNU MediaGoblin's documentation! +=========================================== + +Table of Contents: + +.. toctree:: + :maxdepth: 2 + + foreword + mediagoblin + contributinghowto + deploymenthowto + hackinghowto + theminghowto + git + codebase + designdecisions + vision + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/source/mediagoblin.rst b/docs/source/mediagoblin.rst new file mode 100644 index 00000000..c437ecc3 --- /dev/null +++ b/docs/source/mediagoblin.rst @@ -0,0 +1,70 @@ +================= + GNU MediaGoblin +================= + +.. contents:: Sections + :local: + + +What is GNU MediaGoblin +======================= + +Three years ago (2008), a number of free software luminaries got +together at the FSF office to answer the question, "What should +software freedom look like on the participatory web?" Those thinkers +included Richard Stallman---founder of the free software movement and +instigator of the GNU project, Evan Prodromou---the driving force +behind Status.net, a highly sucessful federated micro-blogging +service, and FIXME. + +Since that time Identi.ca and Libre.fm have answered the +freedom-loving web-user's need for micro-blogging and music sharing. +Now, GNU MediaGoblin is building a format for users to share photos. +Later versions of MediaGoblin will include support for video and other +media as well as tools to encourage collaboration on media projects. + + +Why are we doing this? +====================== + +Centralization and proprietization of media on the internet is a +serious problem and makes the web go from a system of extreme +resilience to a system of frightening fragility. We believe people +should be able to own their data and that means someone has to build +the tools to make it possible. We decided that in this case, that +someone would be us! + + +Who are you? +============ + +Free software activists and folks who have worked on a variety of +other projects like Libre.fm, GNU Social, Status.net, Miro, Miro +Community, OpenHatch and other projects as well. We're admirers and +contributors. We're writers and painters. We're friendly and +dedicated to computer user freedom. + + +How can I participate? +====================== + +See `Get Involved `_ on the website.. + + +How is GNU MediaGoblin licensed? +================================ + +GNU MediaGoblin software is released under an AGPLv3 license. + +See the ``COPYING`` file in the source for details. + + +Is this an official GNU Project? What does that mean? +====================================================== + +We are! It means that we meet the GNU Project's rigourous standards +for free software. To find out more about what that means, check out +`the GNU site `_. + +Please feel free to contact us with further questions! + diff --git a/docs/source/mgext/__init__.py b/docs/source/mgext/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/docs/source/mgext/youcanhelp.py b/docs/source/mgext/youcanhelp.py new file mode 100644 index 00000000..a99d0e4d --- /dev/null +++ b/docs/source/mgext/youcanhelp.py @@ -0,0 +1,44 @@ +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) diff --git a/docs/source/snugglygoblin.png b/docs/source/snugglygoblin.png new file mode 100644 index 00000000..f325ae4b Binary files /dev/null and b/docs/source/snugglygoblin.png differ diff --git a/docs/source/theminghowto.rst b/docs/source/theminghowto.rst new file mode 100644 index 00000000..7b40685f --- /dev/null +++ b/docs/source/theminghowto.rst @@ -0,0 +1,8 @@ +.. _theming-howto: + +=============== + Theming HOWTO +=============== + +We haven't implemented the necessary scaffolding to allow for theming +yet. Thus, this chapter is a stub. diff --git a/docs/source/vision.rst b/docs/source/vision.rst new file mode 100644 index 00000000..fad248df --- /dev/null +++ b/docs/source/vision.rst @@ -0,0 +1,142 @@ +========================================= + Design Document: GNU MediaGoblin vision +========================================= + +.. Note:: + + When we get a wiki, this will get moved there. It's here for now + mostly because we didn't have a better place for it. + +.. Note:: + + By the time you read this, it's very likely it'll be out of date. + + +This document attempts to describe the envisioned workflow of GNU +MediaGoblin, from a structural standpoint. For now, *nothing* in this +document is probably the eventual, final way that things will work. +Eventually as things come to exist, this document will hopefully be +refactored to describe how things *do* work. + +This documented on hopes, dreams, rainbows, and unicorns. And it will +come to fulfillment through a lot of hard work. Your hard work and my +hard work. + + +Look and feel +============= + +Default look and feel +--------------------- + +Mairin Duffy made mockups for something called Design Hub. That +project did a number of things differently than the way we intend to +go, but it's probably a good idea to steal a good number of ideas from +here. + +http://mairin.wordpress.com/2010/03/09/another-design-hub-mockup/ + + +User profile mockup +------------------- + +Here's an ascii art mockup on how things might look for a user's page:: + + _____ + |_( )_| USER NAME + | | | + |_/_\_| + + Recent artwork: + ___________________ ___________________________ + | ___ ___ ___ | |_About_User_Name___________| + | |pic| |pic| |pic| | | | + | |___| |___| |___| | | Some sort of self- | + | ___ ___ ___ | | description probably goes | + < | |pic| |pic| |pic| | > | here | + | |___| |___| |___| | | | + | ___ ___ ___ | | | + | |pic| |pic| |pic| | | | + | |___| |___| |___| | | | + |___________________| |___________________________| + + ___________________________ + Recent favorites: |_Recent_activity___________| + ___________________ | New picture: DragonFace | + | ___ ___ ___ | | 4/2/2010 | + | |pic| |pic| |pic| | |---------------------------| + | |___| |___| |___| | | Sup yall this is some kind| + | ___ ___ ___ | | of mini blogpost. Maybe | + < | |pic| |pic| |pic| | > | the interface will allow | + | |___| |___| |___| | | for this? | + | ___ ___ ___ | |___________________________| + | |pic| |pic| |pic| | + | |___| |___| |___| | ___________________________ + |___________________| |_External_comments_here____| + | Dang! This stuff rocks | + | - Joe 4/2/2010 | + |---------------------------| + | Nice job on the dragon | + | - Morgan 4/2/2010 | + '---------------------------' + +So there's this type of interface that puts a lot of different types +of info on the same screen. I'm not sure that I like it. It's +possible we'll go with something much more minimalist. Maybe we'll go +with something "tabbed" the way statusnet / http://identi.ca is on +user pages. + +It's possible that we could support multiple profile styles here, +and you could load whatever profile style you want as set by user +preferences? + + +Uploading mockup +---------------- + +Here's an uploading mockup:: + + Upload an image + + [ Title ] + + Upload: [ ] [Browse] + ___________________________________________ + | | + | | + | o0O | + | o ' | + | o_.' | + | | + | Uploading... OK | <-, + | Resizing... OK | | + | | Area replaced w/ resized + | | image when done + |___________________________________________| + ________________ + License |_CC BY-SA_____|V| + ___________________________________________ + | Description goes here. | + | You can type it up in here and everything | + | and it'll show up under the image. | + | | + | Possibly we should allow some kind of | + | markup... maybe markdown? | + '___________________________________________' + + __________________________________________ + |> Advanced | + ------------------------------------------ + + +Customizability +--------------- + +General site theming customizability is pretty easy! Since we're +using `Jinja `_ we can just set up +user-overriding directories. + +We'll also figure out some sort of way to provide theming "packages", +eventually. + + diff --git a/docs/theminghowto.rst b/docs/theminghowto.rst deleted file mode 100644 index 7b40685f..00000000 --- a/docs/theminghowto.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _theming-howto: - -=============== - Theming HOWTO -=============== - -We haven't implemented the necessary scaffolding to allow for theming -yet. Thus, this chapter is a stub. diff --git a/docs/vision.rst b/docs/vision.rst deleted file mode 100644 index fad248df..00000000 --- a/docs/vision.rst +++ /dev/null @@ -1,142 +0,0 @@ -========================================= - Design Document: GNU MediaGoblin vision -========================================= - -.. Note:: - - When we get a wiki, this will get moved there. It's here for now - mostly because we didn't have a better place for it. - -.. Note:: - - By the time you read this, it's very likely it'll be out of date. - - -This document attempts to describe the envisioned workflow of GNU -MediaGoblin, from a structural standpoint. For now, *nothing* in this -document is probably the eventual, final way that things will work. -Eventually as things come to exist, this document will hopefully be -refactored to describe how things *do* work. - -This documented on hopes, dreams, rainbows, and unicorns. And it will -come to fulfillment through a lot of hard work. Your hard work and my -hard work. - - -Look and feel -============= - -Default look and feel ---------------------- - -Mairin Duffy made mockups for something called Design Hub. That -project did a number of things differently than the way we intend to -go, but it's probably a good idea to steal a good number of ideas from -here. - -http://mairin.wordpress.com/2010/03/09/another-design-hub-mockup/ - - -User profile mockup -------------------- - -Here's an ascii art mockup on how things might look for a user's page:: - - _____ - |_( )_| USER NAME - | | | - |_/_\_| - - Recent artwork: - ___________________ ___________________________ - | ___ ___ ___ | |_About_User_Name___________| - | |pic| |pic| |pic| | | | - | |___| |___| |___| | | Some sort of self- | - | ___ ___ ___ | | description probably goes | - < | |pic| |pic| |pic| | > | here | - | |___| |___| |___| | | | - | ___ ___ ___ | | | - | |pic| |pic| |pic| | | | - | |___| |___| |___| | | | - |___________________| |___________________________| - - ___________________________ - Recent favorites: |_Recent_activity___________| - ___________________ | New picture: DragonFace | - | ___ ___ ___ | | 4/2/2010 | - | |pic| |pic| |pic| | |---------------------------| - | |___| |___| |___| | | Sup yall this is some kind| - | ___ ___ ___ | | of mini blogpost. Maybe | - < | |pic| |pic| |pic| | > | the interface will allow | - | |___| |___| |___| | | for this? | - | ___ ___ ___ | |___________________________| - | |pic| |pic| |pic| | - | |___| |___| |___| | ___________________________ - |___________________| |_External_comments_here____| - | Dang! This stuff rocks | - | - Joe 4/2/2010 | - |---------------------------| - | Nice job on the dragon | - | - Morgan 4/2/2010 | - '---------------------------' - -So there's this type of interface that puts a lot of different types -of info on the same screen. I'm not sure that I like it. It's -possible we'll go with something much more minimalist. Maybe we'll go -with something "tabbed" the way statusnet / http://identi.ca is on -user pages. - -It's possible that we could support multiple profile styles here, -and you could load whatever profile style you want as set by user -preferences? - - -Uploading mockup ----------------- - -Here's an uploading mockup:: - - Upload an image - - [ Title ] - - Upload: [ ] [Browse] - ___________________________________________ - | | - | | - | o0O | - | o ' | - | o_.' | - | | - | Uploading... OK | <-, - | Resizing... OK | | - | | Area replaced w/ resized - | | image when done - |___________________________________________| - ________________ - License |_CC BY-SA_____|V| - ___________________________________________ - | Description goes here. | - | You can type it up in here and everything | - | and it'll show up under the image. | - | | - | Possibly we should allow some kind of | - | markup... maybe markdown? | - '___________________________________________' - - __________________________________________ - |> Advanced | - ------------------------------------------ - - -Customizability ---------------- - -General site theming customizability is pretty easy! Since we're -using `Jinja `_ we can just set up -user-overriding directories. - -We'll also figure out some sort of way to provide theming "packages", -eventually. - - -- cgit v1.2.3 From 65e7ce634cfecc87ed6f390f9ccf91be513d2eea Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 31 Jul 2011 23:07:13 -0400 Subject: Moves hacking howto and design decisions docs to wiki --- docs/source/codebase.rst | 2 +- docs/source/contributinghowto.rst | 6 +- docs/source/deploymenthowto.rst | 4 +- docs/source/designdecisions.rst | 329 ------------------------------------ docs/source/git.rst | 2 +- docs/source/hackinghowto.rst | 345 -------------------------------------- docs/source/index.rst | 2 - 7 files changed, 7 insertions(+), 683 deletions(-) delete mode 100644 docs/source/designdecisions.rst delete mode 100644 docs/source/hackinghowto.rst (limited to 'docs') diff --git a/docs/source/codebase.rst b/docs/source/codebase.rst index 898eadfe..ba5f1e46 100644 --- a/docs/source/codebase.rst +++ b/docs/source/codebase.rst @@ -21,7 +21,7 @@ various recipes for getting things done. for where we hang out. For more information on how to get started hacking on GNU MediaGoblin, -see :ref:`hacking-howto`. +see `the wiki `_. Software Stack diff --git a/docs/source/contributinghowto.rst b/docs/source/contributinghowto.rst index 06d2814e..a4f5771a 100644 --- a/docs/source/contributinghowto.rst +++ b/docs/source/contributinghowto.rst @@ -46,8 +46,8 @@ Here are some things you can do today: **Write/Fix some code** If you are a coder and you're looking to code, check out the - :ref:`hacking-howto`. We even have tips on *becoming* a coder - and we're willing to help you! + `wiki `_. .. _filing-bugs: diff --git a/docs/source/deploymenthowto.rst b/docs/source/deploymenthowto.rst index f50edfb6..f3093a60 100644 --- a/docs/source/deploymenthowto.rst +++ b/docs/source/deploymenthowto.rst @@ -12,5 +12,5 @@ Step 3: Write the deployment guide and profit! But seriously, this is a stub since we're not quite there (yet) but if you want to see where we are now, you can try to run the latest -development version by following the instructions at -:ref:`hacking-howto`. +development version by following the instructions on +`the wiki `_. diff --git a/docs/source/designdecisions.rst b/docs/source/designdecisions.rst deleted file mode 100644 index afa1e26b..00000000 --- a/docs/source/designdecisions.rst +++ /dev/null @@ -1,329 +0,0 @@ -.. _design-decisions-chapter: - -================== - Design Decisions -================== - -.. contents:: Sections - :local: - - -This chapter talks a bit about design decisions. - - -Why GNU MediaGoblin? -==================== - -Chris and Will on "Why GNU MediaGoblin": - - Chris came up with the name MediaGoblin. The name is pretty fun. - It merges the idea that this is a Media hosting project with - Goblin which sort of sounds like gobbling. Here's a piece of - software that gobbles up your media for all to see. - - `According to Wikipedia `_, a - goblin is: - - a legendary evil or mischievous illiterate creature, described - as grotesquely evil or evil-like phantom - - So are we evil? No. Are we mischievous or illiterate? Not - really. So what kind of goblin are we thinking about? We're - thinking about these goblins: - - .. figure:: goblin.png - :alt: Cute goblin with a beret. - - *Figure 1: Cute goblin with a beret. llustrated by Chris - Webber* - - .. figure:: snugglygoblin.png - :scale: 50% - :alt: Snuggly goblin with a beret. - - *Figure 2: Snuggly goblin. Illustrated by Karen Rustad* - - Those are pretty cute goblins. Those are the kinds of goblins - we're thinking about. - - Chris started doing work on the project after thinking about it - for a year. Then, after talking with Matt and Rob, it became an - official GNU project. Thus we now call it GNU MediaGoblin. - - That's a lot of letters, though, so in the interest of brevity and - facilitating easier casual conversation and balancing that with - what's important to us, we have the following rules: - - 1. "GNU MediaGoblin" is the name we're going to use in all official - capacities: web site, documentation, press releases, ... - - 2. In casual conversation, it's ok to use more casual names. - - 3. If you're writing about the project, we ask that you call it GNU - MediaGoblin. - - 4. If you don't like the name, we kindly ask you to take a deep - breath, think a happy thought about cute little goblins playing - on a playground and taking cute pictures of themselves, and let - it go. (Will added this one.) - - -Why Python -========== - -Chris Webber on "Why Python": - - Because I know Python, love Python, am capable of actually making - this thing happen in Python (I've worked on a lot of large free - software web applications before in Python, including `Miro - Community`_, the `Miro Guide`_, a large portion of `Creative - Commons`_, and a whole bunch of things while working at `Imaginary - Landscape`_). Me starting a project like this makes sense if it's - done in Python. - - You might say that PHP is way more deployable, that Rails has way - more cool developers riding around on fixie bikes---and all of - those things are true. But I know Python, like Python, and think - that Python is pretty great. I do think that deployment in Python - is not as good as with PHP, but I think the days of shared hosting - are (thankfully) coming to an end, and will probably be replaced - by cheap virtual machines spun up on the fly for people who want - that sort of stuff, and Python will be a huge part of that future, - maybe even more than PHP will. The deployment tools are getting - better. Maybe we can use something like Silver Lining. Maybe we - can just distribute as ``.debs`` or ``.rpms``. We'll figure it - out when we get there. - - Regardless, if I'm starting this project, which I am, it's gonna - be in Python. - -.. _Miro Community: http://mirocommunity.org/ -.. _Miro Guide: http://miroguide.org/ -.. _Creative Commons: http://creativecommons.org/ -.. _Imaginary Landscape: http://www.imagescape.com/ - - -Why WSGI Minimalism -=================== - -Chris Webber on "Why WSGI Minimalism": - - If you notice in the technology list I list a lot of components - that are very "django-like", but not actually `Django`_ - components. What can I say, I really like a lot of the ideas in - Django! Which leads to the question: why not just use Django? - - While I really like Django's ideas and a lot of its components, I - also feel that most of the best ideas in Django I want have been - implemented as good or even better outside of Django. I could - just use Django and replace the templating system with Jinja2, and - the form system with wtforms, and the database with MongoDB and - MongoKit, but at that point, how much of Django is really left? - - I also am sometimes saddened and irritated by how coupled all of - Django's components are. Loosely coupled yes, but still coupled. - WSGI has done a good job of providing a base layer for running - applications on and if you know how to do it yourself [1]_, it's - not hard or many lines of code at all to bind them together - without any framework at all (not even say `Pylons`_, `Pyramid`_ - or `Flask`_ which I think are still great projects, especially for - people who want this sort of thing but have no idea how to get - started). And even at this already really early stage of writing - MediaGoblin, that glue work is mostly done. - - Not to say I don't think Django isn't great for a lot of things. - For a lot of stuff, it's still the best, but not for MediaGoblin, - I think. - - One thing that Django does super well though is documentation. It - still has some faults, but even with those considered I can hardly - think of any other project in Python that has as nice of - documentation as Django. It may be worth learning some lessons on - documentation from Django [2]_, on that note. - - I'd really like to have a good, thorough hacking-howto and - deployment-howto, especially in the former making some notes on - how to make it easier for Django hackers to get started. - -.. _Django: http://www.djangoproject.com/ -.. _Pylons: http://pylonshq.com/ -.. _Pyramid: http://docs.pylonsproject.org/projects/pyramid/dev/ -.. _Flask: http://flask.pocoo.org/ - -.. [1] http://pythonpaste.org/webob/do-it-yourself.html -.. [2] http://pycon.blip.tv/file/4881071/ - - -Why MongoDB -=========== - -Chris Webber on "Why MongoDB": - - In case you were wondering, I am not a NOSQL fanboy, I do not go - around telling people that MongoDB is web scale. Actually my - choice for MongoDB isn't scalability, though scaling up really - nicely is a pretty good feature and sets us up well in case large - volume sites eventually do use MediaGoblin. But there's another - side of scalability, and that's scaling down, which is important - for federation, maybe even more important than scaling up in an - ideal universe where everyone ran servers out of their own - housing. As a memory-mapped database, MongoDB is pretty hungry, - so actually I spent a lot of time debating whether the inability - to scale down as nicely as something like SQL has with sqlite - meant that it was out. - - But I decided in the end that I really want MongoDB, not for - scalability, but for flexibility. Schema evolution pains in SQL - are almost enough reason for me to want MongoDB, but not quite. - The real reason is because I want the ability to eventually handle - multiple media types through MediaGoblin, and also allow for - plugins, without the rigidity of tables making that difficult. In - other words, something like:: - - {"title": "Me talking until you are bored", - "description": "blah blah blah", - "media_type": "audio", - "media_data": { - "length": "2:30", - "codec": "OGG Vorbis"}, - "plugin_data": { - "licensing": { - "license": "http://creativecommons.org/licenses/by-sa/3.0/"}}} - - - Being able to just dump media-specific information in a media_data - hashtable is pretty great, and even better is having a plugin - system where you can just let plugins have their own entire - key-value space cleanly inside the document that doesn't interfere - with anyone else's stuff. If we were to let plugins to deposit - their own information inside the database, either we'd let plugins - create their own tables which makes SQL migrations even harder - than they already are, or we'd probably end up creating a table - with a column for key, a column for value, and a column for type - in one huge table called "plugin_data" or something similar. (Yo - dawg, I heard you liked plugins, so I put a database in your - database so you can query while you query.) Gross. - - I also don't want things to be too loose so that we forget or lose - the structure of things, and that's one reason why I want to use - MongoKit, because we can cleanly define a much structure as we - want and verify that documents match that structure generally - without adding too much bloat or overhead (MongoKit is a pretty - lightweight wrapper and doesn't inject extra MongoKit-specific - stuff into the database, which is nice and nicer than many other - ORMs in that way). - - -Why Sphinx for documentation -============================ - -Will Kahn-Greene on "Why Sphinx": - - `Sphinx`_ is a fantastic tool for organizing documentation for a - Python-based project that makes it pretty easy to write docs that - are readable in source form and can be "compiled" into HTML, LaTeX - and other formats. - - There are other doc systems out there, but given that GNU - MediaGoblin is being written in Python and I've done a ton of - documentation using Sphinx, it makes sense to use Sphinx for now. - -.. _Sphinx: http://sphinx.pocoo.org/ - - -Why AGPLv3 and CC0? -=================== - -Chris, Brett, Will, Rob, Matt, et al curated into a story where -everyone is the hero by Will on "Why AGPLv3 and CC0": - - The `AGPL v3`_ preserves the freedoms guaranteed by the GPL v3 in - the context of software as a service. Using this license ensures - that users of the service have the ability to examine the source, - deploy their own instance, and implement their own version. This - is really important to us and a core mission component of this - project. Thus we decided that the software parts should be under - this license. - - However, the project is made up of more than just software: - there's CSS, images, and other output-related things. We wanted - the templates/images/css side of the project all permissive and - permissive in the same absolutely permissive way. We're waiving - our copyrights to non-software things under the CC0 waiver. - - That brings us to the templates where there's some code and some - output. The template engine we're using is called Jinja2. It - mixes HTML markup with Python code to render the output of the - software. We decided the templates are part of the output of the - software and not the software itself. We wanted the output of the - software to be licensed in a hassle-free way so that when someone - deploys their own GNU MediaGoblin instance with their own - templates, they don't have to deal with the copyleft aspects of - the AGPLv3 and we'd be fine with that because the changes they're - making are identity-related. So at first we decided to waive our - copyrights to the templates with a CC0 waiver and then add an - exception to the AGPLv3 for the software such that the templates - can make calls into the software and yet be a separately licensed - work. However, Brett brought up the question of whether this - allows some unscrupulous person to make changes to the software - through the templates in such a way that they're not bound by the - AGPLv3: i.e. a loophole. We thought about this loophole and - between this and the extra legalese involved in the exception to - the AGPLv3, we decided that it's just way simpler if the templates - were also licensed under the AGPLv3. - - Then we have the licensing for the documentation. Given that the - documentation is tied to the software content-wise, we don't feel - like we have to worry about ensuring freedom of the documentation - or worry about attribution concerns. Thus we're waiving our - copyrights to the documentation under CC0 as well. - - Lastly, we have branding. This covers logos and other things that - are distinctive to GNU MediaGoblin that we feel represents this - project. Since we don't currently have any branding, this is an - open issue, but we're thinking we'll go with a CC BY-SA license. - - By licensing in this way, we make sure that users of the software - receive the freedoms that the AGPLv3 ensures regardless of what - fate befalls this project. - - So to summarize: - - * software (Python, JavaScript, HTML templates): licensed - under AGPLv3 - * non-software things (CSS, images, video): copyrights waived - under CC0 because this is output of the software - * documentation: copyrights waived under CC0 because it's not part - of the software - * branding assets: we're kicking this can down the road, but - probably CC BY-SA - - This is all codified in the ``COPYING`` file. - -.. _AGPL v3: http://www.gnu.org/licenses/agpl.html -.. _CC0 v1: http://creativecommons.org/publicdomain/zero/1.0/ - - -Why (non-mandatory) copyright assignment? -========================================= - -Chris Webber on "Why copyright assignment?": - - GNU MediaGoblin is a GNU project with non-mandatory but heavily - encouraged copyright assignment to the FSF. Most, if not all, of - the core contributors to GNU MediaGoblin will have done a - copyright assignment, but unlike some other GNU projects, it isn't - required here. We think this is the best choice for GNU - MediaGoblin: it ensures that the Free Software Foundation may - protect the software by enforcing the AGPL if the FSF sees fit, - but it also means that we can immediately merge in changes from a - new contributor. It also means that some significant non-FSF - contributors might also be able to enforce the AGPL if seen fit. - - Again, assignment is not mandatory, but it is heavily encouraged, - even incentivized: significant contributors who do a copyright - assignment to the FSF are eligible to have a unique goblin drawing - produced for them by the project's main founder, Christopher Allan - Webber. See :ref:`contributing-howto-chapter` for details. - - diff --git a/docs/source/git.rst b/docs/source/git.rst index bd0f9d52..ab3206b6 100644 --- a/docs/source/git.rst +++ b/docs/source/git.rst @@ -221,4 +221,4 @@ because he doesn't need it anymore. How to learn git ================ -Check out :ref:`hacking-howto-git`! +Check out `the wiki `_. diff --git a/docs/source/hackinghowto.rst b/docs/source/hackinghowto.rst deleted file mode 100644 index caafba53..00000000 --- a/docs/source/hackinghowto.rst +++ /dev/null @@ -1,345 +0,0 @@ -.. _hacking-howto: - -=============== - Hacking HOWTO -=============== - -.. contents:: Sections - :local: - - -So you want to hack on GNU MediaGoblin? -======================================= - -First thing to do is check out the `Web site -`_ where we list all the project -infrastructure including: - -* the IRC channel -* 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. - -Third you'll need to :ref:`get the requirements -`. - -Fourth, you'll need to build a development environment. We use buildout, -but if you want to use virtualenv, there's a set of mediocre not-very-supported -steps in the `wiki `_. - - -.. _get-requirements-section: - -Getting requirements -==================== - -First, you need to have the following installed before you can build -an environment for hacking on GNU MediaGoblin: - -* Python 2.6 or 2.7 - http://www.python.org/ - - You'll need Python as well as the dev files for building modules. - -* python-lxml - http://lxml.de/ -* git - http://git-scm.com/ -* MongoDB - http://www.mongodb.org/ - -If you're running Debian GNU/Linux or a Debian-derived distribution -such as Mint or Ubuntu, running the following should install these -requirements:: - - sudo apt-get install mongodb git-core python python-dev \ - python-lxml - -On Fedora:: - - yum install mongodb-server python-paste-deploy python-paste-script \ - git-core python python-devel python-lxml - -.. YouCanHelp:: - - If you have instructions for other GNU/Linux distributions to set - up requirements, let us know! - - -.. _hacking-with-buildout: - - -How to set up and maintain an environment for hacking with buildout -=================================================================== - -**Requirements** - -No additional requirements. - - -**Create a development environment** - -After installing the requirements, follow these steps: - -1. Clone the repository:: - - git clone git://gitorious.org/mediagoblin/mediagoblin.git - -2. Bootstrap and run buildout:: - - cd mediagoblin - python bootstrap.py && ./bin/buildout - - -That's it! Using this method, buildout should create a ``user_dev`` -directory, in which certain things will be stored (media, beaker -session stuff, etc). You can change this, but for development -purposes this default should be fine. - - -**Updating for dependency changes** - -While hacking on GNU MediaGoblin over time, you'll eventually have to -update your development environment because the dependencies have -changed. To do that, run:: - - ./bin/buildout && ./bin/gmg migrate - - -**Updating for code changes** - -You don't need to do anything---code changes are automatically -available. - - -**Deleting your buildout** - -At some point, you may want to delete your buildout. Perhaps it's to -start over. Perhaps it's to test building development environments -with buildout. - -To do this, do:: - - rm -rf bin develop-eggs eggs mediagoblin.egg-info parts user_dev - - -Running the server -================== - -If you want to get things running quickly and without hassle, just -run:: - - ./lazyserver.sh - -This will start up a python server where you can begin playing with -mediagoblin. It will also run celery in "always eager" mode so you -don't have to start a separate process for it. - -This is fine in development, but if you want to actually run celery -separately for testing (or deployment purposes), you'll want to run -the server independently:: - - ./bin/paster serve paste.ini --reload - - -Running celeryd -=============== - -If you aren't using ./lazyserver.sh or otherwise aren't running celery -in always eager mode, you'll need to do this if you want your media to -process and actually show up. It's probably a good idea in -development to have the web server (above) running in one terminal and -celeryd in another window. - -Run:: - - CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd - - -Running the test suite -====================== - -Run:: - - ./runtests.sh - - -Running a shell -=============== - -If you want a shell with your database pre-setup and an instantiated -application ready and at your fingertips.... - -Run:: - - ./bin/gmg shell - - -Troubleshooting -=============== - -pymongo.errors.AutoReconnect: could not find master/primary ------------------------------------------------------------ - -If you see this:: - - pymongo.errors.AutoReconnect: could not find master/primary - -then make sure mongodb is installed and running. - -If it's installed, check the mongodb log. On my machine, that's -``/var/log/mongodb/mongodb.log``. If you see something like:: - - old lock file: /var/lib/mongodb/mongod.lock. probably means... - -in that case you might have had an unclean shutdown. Try:: - - sudo mongod --repair - -If that didn't work, just delete the lock file and relaunch mongodb. - -Anyway, then start the mongodb server in whatever way is appropriate -for your distro / OS. - - -pkg_resources.DistributionNotFound: distribute ----------------------------------------------- - -If you get this while running buildout:: - - pkg_resources.DistributionNotFound: distribute - -Try this commmand instead:: - - python bootstrap.py --distribute && ./bin/buildout - - -Wiping your user data -===================== - -.. Note:: - - Unless you're doing development and working on and testing creating - a new instance, you will probably never have to do this. Will - plans to do this work and thus he documented it. - -.. YouCanHelp:: - - If you're familiar with MongoDB, we'd love to get a `script that - removes all the GNU MediaGoblin data from an existing instance - `_. Let us know! - - -Quickstart for Django programmers -================================= - -We're not using Django, but the codebase is very Django-like in its -structure. - -* ``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. - - -.. YouCanHelp:: - - 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 -============================= - -**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 `_ or -on the `IRC channel `_. - - -Tips for people new to coding -============================= - -Learning Python ---------------- - -GNU MediaGoblin is written using a programming language called `Python -`_. - -There are two different incompatible iterations of Python which I'll -refer to as Python 2 and Python 3. GNU MediaGoblin is written in -Python 2 and requires Python 2.6 or 2.7. At some point, we might -switch to Python 3, but that's a future thing. - -You can learn how to code in Python 2 from several excellent books -that are freely available on the Internet: - -* `Learn Python the Hard Way `_ -* `Dive Into Pyton `_ -* `Python for Software Design `_ -* `A Byte of Python `_ - -These are all excellent texts. - -.. YouCanHelp:: - - If you know of other good quality Python tutorials and Python - tutorial videos, let us know! - - -Learning Libraries GNU MediaGoblin uses ---------------------------------------- - -GNU MediaGoblin uses a variety of libraries in order to do what it -does. These libraries are listed in the :ref:`codebase-chapter` -along with links to the project Web sites and documentation for the -libraries. - -There are a variety of Python-related conferences every year that have -sessions covering many aspects of these libraries. You can find them -at `Python Miro Community `_ [0]_. - -.. [0] This is a shameless plug. Will Kahn-Greene runs Python Miro - Community. - -If you have questions or need help, find us on the mailing list and on -IRC. - - -.. _hacking-howto-git: - -Learning git ------------- - -git is an interesting and very powerful tool. Like all powerful -tools, it has a learning curve. - -If you're new to git, we highly recommend the following resources for -getting the hang of it: - -* `Learn Git `_ --- the GitHub - intro to git -* `Pro Git `_ --- fantastic book -* `Git casts `_ --- screencast covering git - usage -* `Git Reference `_ --- Git reference that makes - it easier to get the hang of git if you're coming from other version - control systems - -There's also a git mission at `OpenHatch `_. - - -Learning other utilities ------------------------- - -The `OpenHatch `_ site has a series of -`training missions `_ which are -designed to help you learn how to use these tools. - -If you're new to tar, diff, patch and git, we highly recommend you sign -up with OpenHatch and do the missions. diff --git a/docs/source/index.rst b/docs/source/index.rst index 2f84d6a6..8c00869a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,11 +15,9 @@ Table of Contents: mediagoblin contributinghowto deploymenthowto - hackinghowto theminghowto git codebase - designdecisions vision -- cgit v1.2.3 From cd57611f95191ba9b1d58a11dd8eb42d3c9185e0 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 1 Aug 2011 09:54:09 -0500 Subject: Phrasing update: "own your data" -> "free your data from proprietary control" --- docs/source/mediagoblin.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/source/mediagoblin.rst b/docs/source/mediagoblin.rst index c437ecc3..af6658f3 100644 --- a/docs/source/mediagoblin.rst +++ b/docs/source/mediagoblin.rst @@ -30,9 +30,9 @@ Why are we doing this? Centralization and proprietization of media on the internet is a serious problem and makes the web go from a system of extreme resilience to a system of frightening fragility. We believe people -should be able to own their data and that means someone has to build -the tools to make it possible. We decided that in this case, that -someone would be us! +should be able to free their data from proprietary control and that +means someone has to build the tools to make it possible. We decided +that in this case, that someone would be us! Who are you? -- cgit v1.2.3 From c7f0b6fab08a52cc5a6e242ad3df2e674cb68fb9 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 1 Aug 2011 12:17:03 -0400 Subject: Updating version to 0.0.4. --- docs/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/source/conf.py b/docs/source/conf.py index 5861a463..e2f327c9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -48,9 +48,9 @@ copyright = u'2011, Free Software Foundation, Inc and contributors' # built documents. # # The short X.Y version. -version = '0.0.3' +version = '0.0.4' # The full version, including alpha/beta/rc tags. -release = '0.0.3' +release = '0.0.4' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3