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/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 +++++++++ 20 files changed, 2179 insertions(+) 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 (limited to 'docs/source') 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. + + -- 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/source') 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/source') 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/source') 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 From abbc6c1a550d3aa8bab11fc67561e134d65ac5e6 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 21 Aug 2011 21:54:54 -0500 Subject: Updating the mediagoblin manual's foreward: - Removing contributors section of the foreward... we should have a contributors list, but it doesn't belong here. - Specifying that this manual is not contributor-oriented... it's for local users/administrators - Updating issue tracker link - Adjusting the "living document" line to mention http://docs.mediagoblin.org --- docs/source/foreword.rst | 29 +++++++++++------------------ 1 file changed, 11 insertions(+), 18 deletions(-) (limited to 'docs/source') diff --git a/docs/source/foreword.rst b/docs/source/foreword.rst index 1d423f08..4fd96842 100644 --- a/docs/source/foreword.rst +++ b/docs/source/foreword.rst @@ -8,26 +8,19 @@ 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. +* people who want to try the software locally +* people who want to deploy and administrate the software +This manual doesn't cover contributors to the codebase. But we want +and love contributors! To join as a contributor please visit the +following pages instead: -Who wrote this documentation? -============================= +* http://mediagoblin.org/pages/join.html for general "join us" information +* http://wiki.mediagoblin.org/ for our contributor-focused wiki -In no particular order: - -* Chris -* Will -* Deb -* Greg -* Karen -* Matt -* Asheesh +If you are viewing this from http://docs.mediagoblin.org be aware that +this manual is a living document and is in the ``mediagoblin`` +repository in the ``docs/`` directory. I found an error in the docs---who do I tell? @@ -35,7 +28,7 @@ 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/ . +1. Write up a bug report in the bug tracker at http://bugs.foocorp.net/projects/mediagoblin/issues 2. Tell someone on IRC ``#mediagoblin`` on Freenode. 3. Send an email to Will ``willg at bluesock dot org``. -- cgit v1.2.3 From 26924b717efe7942593c992999a792de36dc82f4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 21 Aug 2011 22:23:03 -0500 Subject: Changing the MediaGoblin Sphinx docs a bit... - Removing the git guide, and moved it to the wiki - moving mediagoblin.rst to about_mediagoblin.rst --- docs/source/about_mediagoblin.rst | 70 ++++++++++++ docs/source/git.rst | 224 -------------------------------------- docs/source/index.rst | 5 +- docs/source/mediagoblin.rst | 70 ------------ 4 files changed, 72 insertions(+), 297 deletions(-) create mode 100644 docs/source/about_mediagoblin.rst delete mode 100644 docs/source/git.rst delete mode 100644 docs/source/mediagoblin.rst (limited to 'docs/source') diff --git a/docs/source/about_mediagoblin.rst b/docs/source/about_mediagoblin.rst new file mode 100644 index 00000000..af6658f3 --- /dev/null +++ b/docs/source/about_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 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? +============ + +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/git.rst b/docs/source/git.rst deleted file mode 100644 index ab3206b6..00000000 --- a/docs/source/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 `the wiki `_. diff --git a/docs/source/index.rst b/docs/source/index.rst index 8c00869a..79f2653e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,11 +12,10 @@ Table of Contents: :maxdepth: 2 foreword - mediagoblin - contributinghowto + about_mediagoblin deploymenthowto theminghowto - git + contributinghowto codebase vision diff --git a/docs/source/mediagoblin.rst b/docs/source/mediagoblin.rst deleted file mode 100644 index af6658f3..00000000 --- a/docs/source/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 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? -============ - -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! - -- cgit v1.2.3 From 6503d66c98765802836b09fb9f6a5f2ad47ad47a Mon Sep 17 00:00:00 2001 From: tycho garen Date: Sat, 27 Aug 2011 17:43:14 -0400 Subject: Documentation Revision, clarification, and editing. - a line in the .gitignore file to ignore the built documentation tree. - a complete revision/editorial pass of all non-technical documents that outline process, project fundamentals, and background. These edits clarified the text, unified the style, and elaborated on stubs. --- docs/source/about_mediagoblin.rst | 95 +++++++------- docs/source/contributinghowto.rst | 262 +++++++++++++++++++++----------------- docs/source/foreword.rst | 51 ++++---- docs/source/index.rst | 5 +- 4 files changed, 230 insertions(+), 183 deletions(-) (limited to 'docs/source') diff --git a/docs/source/about_mediagoblin.rst b/docs/source/about_mediagoblin.rst index af6658f3..71d8b89c 100644 --- a/docs/source/about_mediagoblin.rst +++ b/docs/source/about_mediagoblin.rst @@ -9,43 +9,52 @@ 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 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? -============ - -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? +In 2008 a number of free software developers and activists gathered at +the FSF to attempt to answer the question "What should software +freedom look like on the participatory web?" Their answer, the +`Franklin Street Statement `_, +has lead to the development of `autonomo.us `_ +community, and free software projects including `Identi.ca `_ +and `Libre.fm `_. + +Identi.ca and Libre.fm address the need for micro-blogging and music +sharing services and software that respect users' freedom and +autonomy. GNU MediaGoblin emerges from this milieu to create a +platform for us to share photos in an environment that respects our +freedom and independence. In the future MediaGoblin will include +support other media, like video, and provide tools to facilitate +collaboration on media projects. + +Why Build GNU MediaGoblin +========================= + +The Internet is designed--and works best--as a complex and endlessly +resilient network. When key services and media outlets are +concentrated in centralized platforms, the network becomes less useful +and increasingly fragile. As always, the proprietary nature of these +systems, hinders users ability to develop, extend, and understand +their software; however, in the case of network services it also means +that users must forfeit control of their data to the service +providers. + +Therefore, we believe that network services must be federated to avoid +centralization and that everyone ought to have control over their +data. In support of this, we've decided to help build the tools to +make these kinds of services possible. We hope you'll join us, both as +users and as contributors. + +Who Contributes to the Project +============================== + +You do! + +We are free software activists and folks who have worked on a variety +of other projects including: Libre.fm, GNU Social, Status.net, Miro, +Miro Community, and OpenHatch among others. We're programmers, +musicians, writers, and painters. We're friendly and dedicated to +software and network freedom. + +How Can I Participate? ====================== See `Get Involved `_ on the website.. @@ -56,15 +65,15 @@ How is GNU MediaGoblin licensed? GNU MediaGoblin software is released under an AGPLv3 license. -See the ``COPYING`` file in the source for details. +See the ``COPYING`` file in the source repository for details. -Is this an official GNU Project? What does that mean? -====================================================== +Is MedaGobilin 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 `_. +MediaGoblin is an official GNU project! This status means that we the +meet the GNU Project's rigorous 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/contributinghowto.rst b/docs/source/contributinghowto.rst index a4f5771a..8eaff5e4 100644 --- a/docs/source/contributinghowto.rst +++ b/docs/source/contributinghowto.rst @@ -1,185 +1,215 @@ .. _contributing-howto-chapter: -==================== - Contributing HOWTO -==================== +=================================== +HOWTO Contribute to GNU MediaGoblin +=================================== .. 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: - +We're **really** glad that you want to join the MediaGoblin community! - **Hang out with us** +There are a variety of ways to help and support MediaGoblin and to +join the team. If you want to code, great, if not, even better! +MediaGoblin interested contributors in many different roles: users, +system administrators, technical writers, testers, evangelists, +UI/UX and graphics designers, cheerleaders, and dreamers. - You should hang out with us! We like people like you! +This document provides an overview of different ways you can get +involved with MediaGoblin along with instructions for getting +started. There is some obvious overlap with `the "join" page on +mediagoblin.org `_ at present. - At a bare minimum, join the `mailing list - `_ and say, "Hi!" +Hang out with the MediaGoblin folk +---------------------------------- - We also hang out on IRC in ``#mediagoblin`` on Freenode.net. +MediaGoblin has a `discussion listserv `_, +and an IRC (``#mediagoblin``) channel on `freenode.net `_. +Don't be afraid to drop by and say "Hi!" And, if you're looking for +something to do, just ask: there's always work to be done. - **File bugs** +File Bugs / Triage Bugs +----------------------- - Filing bugs is a critical part of any project. For more - information on filing bugs, see :ref:`filing-bugs`. +Issue reports are critical for all projects. Identified bugs give +developers a basis for beginning work, and providing an idea of what +features and issues are most important to users and the overall +usability of the software. If you identify errors, flaws, unexpected +behaviors, or deficits that impede use, file a bug. +See the section on `filing bugs <#filing-bugs>`_ for more information on how to file the best +and most useful bug reports. - **Write/Fix some code** +If you want to contribute to MediaGoblin and don't know where to +start, look at the `bug database `_ +as a starting point. - If you are a coder and you're looking to code, check out the - `wiki `_ for suggestions on how +to most effectively triage and approach the issue queue. +Write/Fix Code +-------------- - **Send encouragement** +If you are a coder and you would like to write code, the `repository `_ +is hosted on `gitorious `_. Clone or fork the +repository and start poking around. Become familiar with this `manual `_ +for an overview of how the software works and is used. Consider the +`contributor wiki `_ for more +information about the project, our preferred methods, and guides for +developing MediaGoblin. We even have tips on *becoming* a coder and +we're willing to help! - 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 Encouragement, Spread the Word +----------------------------------- - Send it to the `mailing list `_ - or hop into ``#mediagoblin`` on Freenode.net and let us know. +Sometimes, a nice word, simple encouragement, and interest in the work +we're doing is enough to inspire a tizzy of productive work. Just a +bit more interest and encouragement can even make the difference +between a complete feature and limited functionality; between a +completed milestone and lost momentum. +Similarly, MediaGoblin, and the movement for free network services, is +always in need of encouragement. Use free network services, understand +the `principals `_ +behind the movement, be able to articulate the benefits of free +network services and the problems with psudo-free applications that +don't respect the users' freedom. - **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? +Write a blog post, post a status update, drop by the `listserv `_ +or join ``#mediagoblin`` on freenode.net and let us know. +Participate in MediaGoblin +========================== 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. +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. - **Help other users** +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. - 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. +Help Others +----------- - **Run your own instance** +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. - 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`. +Run your own MediaGoblin Instance +--------------------------------- - **Translate GNU MediaGoblin** +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! - 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`. +For more information on deploying your own instance, see +the `Deployment HOWTO `_ +.. _translating: -Contributing thank you drawings / copyright assignment -====================================================== +Translate MediaGoblin +--------------------- -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. +If you know English and another language and feel comfortable +translating elements of the interface or even the documentation, +we'd love to have help translating the software and resources. -For why we're doing copyright assignment, see the -`wiki `_. +Create a Theme +-------------- +MedaGoblin development is premised on the idea that the entire +interface for the platform be completely theme-able. If you have a +design or theming background, consider developing themes for +MediaGoblin. New themes help test the theming system, provide +attractive and appealing interfaces for prospective users. If you want +to start a new theme but don't know where to start, touch base with +the development community on the list or in the IRC channel for more +information. .. _filing-bugs: -File bugs +File Bugs ========= -GNU MediaGoblin uses a bug tracker called `Redmine -`_. +MediaGoblin uses a bug tracker called `Redmine `_. -The bug tracker is at ``_. +Our instance is located at ``_. -A good bug report has the following things in it: +The most useful bug reports have the following components: 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. + as well as the context. Consider: - * If it's a bug, can you reproduce it? Is the issue specific to a - browser, computer, image, ...? + * If you think you've found a bug, can you reproduce it in a + controlled environment? Is the issue specific to a browser, + computer, image, media type, or other dimension? All data helps. - * 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? + * If you're submitting 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! +That's it! -If you don't hear from anyone in a couple of weeks, find someone on -IRC. +The better the issue report, the easier it is to address the bug, and +the more likely that the developers will be able to resolve the +issue. If someone has questions about the bug report, they may reach +out to the reporter directly. +If you get a response after a couple of weeks, find someone on IRC. -.. _translating: +.. _triage-bugs: + +Triage Bugs +=========== + +The triage process involves reviewing bugs, removing duplicates, +validating that the issues described are reproducible, ensuring that +the exact behavior is properly documented, diagnosing the cause of +each issue, and working with developers to ensure that critical bugs +get addressed. In many cases, developers do this kind of work as a +matter of course, but one need not be able to code in order to help +working with bugs. + +To triage bugs, go to the `bug tracker `_ +and begin reviewing the open issues. If you are able, attempt to: -Translate GNU MediaGoblin -========================= +- ensure that one or two people in addition to the initial reporter + have been able to reproduce the issue. -Coming soon when we set up translation infrastructure. +- document the issue more clearly. If you had any trouble reproducing + the issue, provide any elucidating information that you can to help + others solve the problem more effectively. + +- find a way to resolve the problem or provide a workaround. +For help, instructions, and suggestions be in touch with the +development community on the list or in the IRC channel for more +information. With many eyes, all bugs are shallow. -Where to go when you get stuck -============================== +How to Get Help with MediaGoblin +================================ -Go to `our Web site `_ where we list the -various places we hang out and how to get a hold of us. +The usual channels, the IRC channel, the listserv, the bug tracker, +are all great ways to be in touch with us. Check the `web site `_ +for more specific contact information. diff --git a/docs/source/foreword.rst b/docs/source/foreword.rst index 4fd96842..c525d002 100644 --- a/docs/source/foreword.rst +++ b/docs/source/foreword.rst @@ -1,39 +1,46 @@ -========== - Foreword -========== +======== +Foreword +======== -About this manual -================= +About the MediaGoblin Manual +============================ -This is the GNU MediaGoblin manual. This documentation targets the -following groups of individuals: +Welcome to the GNU MediaGoblin manual. This document targets several +classes of users, including: -* people who want to try the software locally -* people who want to deploy and administrate the software +* users who would like to try the software locally, +* systems administrators who want to deploy and administer the + software in "production environments," and +* anyone who wants to learn how MediaGoblin works. -This manual doesn't cover contributors to the codebase. But we want -and love contributors! To join as a contributor please visit the -following pages instead: +Some information relevant to the MediaGoblin community members, +including how to get involved (We want and love contributors!) To join +as a contributor please see the following pages: * http://mediagoblin.org/pages/join.html for general "join us" information * http://wiki.mediagoblin.org/ for our contributor-focused wiki -If you are viewing this from http://docs.mediagoblin.org be aware that -this manual is a living document and is in the ``mediagoblin`` -repository in the ``docs/`` directory. +If you suspect that documentation on http://docs.mediagoblin.org is +out of date, it might be. The documentation is updated regularly and +the "living" version of this resource resides in the ``mediagoblin`` +repository with the project's source code the ``docs/`` directory. +Improving the MediaGobiin Manual +================================ -I found an error in the docs---who do I tell? -============================================= - -There are a few ways---please pick the one most convenient to you! +There are a few ways---please pick whichever method is convenient for +you! 1. Write up a bug report in the bug tracker at http://bugs.foocorp.net/projects/mediagoblin/issues 2. Tell someone on IRC ``#mediagoblin`` on Freenode. -3. Send an email to Will ``willg at bluesock dot org``. +3. Send an email to Will ``willg at bluesock dot org``, or Sam at + ``sam@cyborginstitute.com`` 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 +* what the issue is, and +* your thoughts on how to resolve it. + +We hope these materials are useful and we look forward to any and all +feedback. diff --git a/docs/source/index.rst b/docs/source/index.rst index 79f2653e..93b2a942 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,7 +23,8 @@ Table of Contents: Indices and tables ================== -* :ref:`genindex` -* :ref:`modindex` * :ref:`search` +* :ref:`genindex` + +.. * :ref:`modindex` -- cgit v1.2.3 From 05d5d45bf9db4ffe6f7987a8c66e9f547fb1ce15 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 1 Sep 2011 21:10:33 -0400 Subject: Updates version number in docs --- docs/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index e2f327c9..7ea3a340 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.4' +version = '0.0.5' # The full version, including alpha/beta/rc tags. -release = '0.0.4' +release = '0.0.5' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From 917d4663afedded7e6606b1a799771da8dc2a37c Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 5 Oct 2011 23:08:53 -0400 Subject: Overhauls docs * Removes a bunch of content that doesn't need to be in the suer manual anymore. * Fixes issues so it's more readable in source form. * Adds help chapter. * Moves links out of paragraphs to reduce line length. * Cleans up some language. * Fixes some links. --- docs/source/about.rst | 88 ++++++++++++++++ docs/source/about_mediagoblin.rst | 79 -------------- docs/source/codebase.rst | 21 ++-- docs/source/contributinghowto.rst | 215 -------------------------------------- docs/source/deploying.rst | 16 +++ docs/source/deploymenthowto.rst | 16 --- docs/source/foreword.rst | 37 +++---- docs/source/help.rst | 16 +++ docs/source/index.rst | 9 +- docs/source/theming.rst | 8 ++ docs/source/theminghowto.rst | 8 -- docs/source/vision.rst | 142 ------------------------- 12 files changed, 152 insertions(+), 503 deletions(-) create mode 100644 docs/source/about.rst delete mode 100644 docs/source/about_mediagoblin.rst delete mode 100644 docs/source/contributinghowto.rst create mode 100644 docs/source/deploying.rst delete mode 100644 docs/source/deploymenthowto.rst create mode 100644 docs/source/help.rst create mode 100644 docs/source/theming.rst delete mode 100644 docs/source/theminghowto.rst delete mode 100644 docs/source/vision.rst (limited to 'docs/source') diff --git a/docs/source/about.rst b/docs/source/about.rst new file mode 100644 index 00000000..1a2df809 --- /dev/null +++ b/docs/source/about.rst @@ -0,0 +1,88 @@ +======================= + About GNU MediaGoblin +======================= + +.. contents:: Sections + :local: + + +What is GNU MediaGoblin +======================= + +In 2008, a number of free software developers and activists gathered +at the FSF to attempt to answer the question "What should software +freedom look like on the participatory web?" Their answer, the +`Franklin Street Statement`_ has lead to the development of +`autonomo.us`_ community, and free software projects including +`Identi.ca`_ and `Libre.fm`_. + +.. _Franklin Street Statement: http://autonomo.us/2008/07/franklin-street-statement/ +.. _autonomo.us: http://autonomo.us/ +.. _identi.ca: http://identi.ca/ +.. _Libre.fm: http://libre.fm/ + +Identi.ca and Libre.fm address the need for micro-blogging and music +sharing services and software that respect users' freedom and +autonomy. GNU MediaGoblin emerges from this milieu to create a +platform for us to share photos in an environment that respects our +freedom and independence. In the future MediaGoblin will include +support other media, like video, and provide tools to facilitate +collaboration on media projects. + + +Why Build GNU MediaGoblin +========================= + +The Internet is designed---and works best---as a complex and endlessly +resilient network. When key services and media outlets are +concentrated in centralized platforms, the network becomes less useful +and increasingly fragile. As always, the proprietary nature of these +systems, hinders users ability to develop, extend, and understand +their software; however, in the case of network services it also means +that users must forfeit control of their data to the service +providers. + +Therefore, we believe that network services must be federated to avoid +centralization and that everyone ought to have control over their +data. In support of this, we've decided to help build the tools to +make these kinds of services possible. We hope you'll join us, both +as users and as contributors. + + +Who Contributes to the Project +============================== + +You do! + +We are free software activists and folks who have worked on a variety +of other projects including: Libre.fm, GNU Social, Status.net, Miro, +Miro Community, and OpenHatch among others. We're programmers, +musicians, writers, and painters. We're friendly and dedicated to +software and network freedom. + + +How Can I Participate? +====================== + +See `Get Involved `_ on the website. We +eagerly look forward to seeing you! + + +How is GNU MediaGoblin licensed? +================================ + +GNU MediaGoblin software is released under an AGPLv3 license. + +See the ``COPYING`` file in the root of the source for details. + + +Is MedaGobilin an official GNU project? What does that mean? +============================================================= + +MediaGoblin is an official GNU project! This status means that we the +meet the GNU Project's rigorous standards for free software. To find +out more about what that means, check out the `GNU website`_. + +Please feel free to contact us with further questions! + +.. _GNU website: http://gnu.org/ diff --git a/docs/source/about_mediagoblin.rst b/docs/source/about_mediagoblin.rst deleted file mode 100644 index 71d8b89c..00000000 --- a/docs/source/about_mediagoblin.rst +++ /dev/null @@ -1,79 +0,0 @@ -================= - GNU MediaGoblin -================= - -.. contents:: Sections - :local: - - -What is GNU MediaGoblin -======================= - -In 2008 a number of free software developers and activists gathered at -the FSF to attempt to answer the question "What should software -freedom look like on the participatory web?" Their answer, the -`Franklin Street Statement `_, -has lead to the development of `autonomo.us `_ -community, and free software projects including `Identi.ca `_ -and `Libre.fm `_. - -Identi.ca and Libre.fm address the need for micro-blogging and music -sharing services and software that respect users' freedom and -autonomy. GNU MediaGoblin emerges from this milieu to create a -platform for us to share photos in an environment that respects our -freedom and independence. In the future MediaGoblin will include -support other media, like video, and provide tools to facilitate -collaboration on media projects. - -Why Build GNU MediaGoblin -========================= - -The Internet is designed--and works best--as a complex and endlessly -resilient network. When key services and media outlets are -concentrated in centralized platforms, the network becomes less useful -and increasingly fragile. As always, the proprietary nature of these -systems, hinders users ability to develop, extend, and understand -their software; however, in the case of network services it also means -that users must forfeit control of their data to the service -providers. - -Therefore, we believe that network services must be federated to avoid -centralization and that everyone ought to have control over their -data. In support of this, we've decided to help build the tools to -make these kinds of services possible. We hope you'll join us, both as -users and as contributors. - -Who Contributes to the Project -============================== - -You do! - -We are free software activists and folks who have worked on a variety -of other projects including: Libre.fm, GNU Social, Status.net, Miro, -Miro Community, and OpenHatch among others. We're programmers, -musicians, writers, and painters. We're friendly and dedicated to -software and network 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 repository for details. - - -Is MedaGobilin an official GNU project? What does that mean? -============================================================= - -MediaGoblin is an official GNU project! This status means that we the -meet the GNU Project's rigorous 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/codebase.rst b/docs/source/codebase.rst index ba5f1e46..28d73802 100644 --- a/docs/source/codebase.rst +++ b/docs/source/codebase.rst @@ -45,7 +45,7 @@ Software Stack * Web application - * `Paste Deploy `_ and + * `Paste Deploy `_ and `Paste Script `_: we'll use this for configuring and launching the application @@ -83,22 +83,21 @@ After you've run buildout, you're faced with the following directory tree:: mediagoblin/ - |- mediagoblin/ #source code + |- mediagoblin/ # source code | |- tests/ | |- templates/ | |- auth/ | \- submit/ - |- docs/ #documentation + |- docs/ # documentation | - | #the below directories are generated by - | #buildout. + | # the below directories are generated by buildout. | - |- bin/ #scripts + |- bin/ # scripts |- develop-eggs/ |- eggs/ |- mediagoblin.egg-info/ |- parts/ - |- user_dev/ #sessions, etc + |- user_dev/ # sessions, etc As you can see, all the code for GNU MediaGoblin is in the @@ -108,7 +107,7 @@ Here are some interesting files and what they do: :routing.py: maps url paths to views :views.py: views handle http requests -:models.py: holds the mongodb schemas---these are the data structures +: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, @@ -122,9 +121,3 @@ templates, auth, submit, ... 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/contributinghowto.rst b/docs/source/contributinghowto.rst deleted file mode 100644 index 8eaff5e4..00000000 --- a/docs/source/contributinghowto.rst +++ /dev/null @@ -1,215 +0,0 @@ -.. _contributing-howto-chapter: - -=================================== -HOWTO Contribute to GNU MediaGoblin -=================================== - -.. contents:: Sections - :local: - -.. _join-the-community-section: - -Join the community! -=================== - -We're **really** glad that you want to join the MediaGoblin community! - -There are a variety of ways to help and support MediaGoblin and to -join the team. If you want to code, great, if not, even better! -MediaGoblin interested contributors in many different roles: users, -system administrators, technical writers, testers, evangelists, -UI/UX and graphics designers, cheerleaders, and dreamers. - -This document provides an overview of different ways you can get -involved with MediaGoblin along with instructions for getting -started. There is some obvious overlap with `the "join" page on -mediagoblin.org `_ at present. - -Hang out with the MediaGoblin folk ----------------------------------- - -MediaGoblin has a `discussion listserv `_, -and an IRC (``#mediagoblin``) channel on `freenode.net `_. - -Don't be afraid to drop by and say "Hi!" And, if you're looking for -something to do, just ask: there's always work to be done. - -File Bugs / Triage Bugs ------------------------ - -Issue reports are critical for all projects. Identified bugs give -developers a basis for beginning work, and providing an idea of what -features and issues are most important to users and the overall -usability of the software. If you identify errors, flaws, unexpected -behaviors, or deficits that impede use, file a bug. - -See the section on `filing bugs <#filing-bugs>`_ for more information on how to file the best -and most useful bug reports. - -If you want to contribute to MediaGoblin and don't know where to -start, look at the `bug database `_ -as a starting point. - -See the section on `bug triage <#triage-bugs>`_ for suggestions on how -to most effectively triage and approach the issue queue. - -Write/Fix Code --------------- - -If you are a coder and you would like to write code, the `repository `_ -is hosted on `gitorious `_. Clone or fork the -repository and start poking around. Become familiar with this `manual `_ -for an overview of how the software works and is used. Consider the -`contributor wiki `_ for more -information about the project, our preferred methods, and guides for -developing MediaGoblin. We even have tips on *becoming* a coder and -we're willing to help! - -Send Encouragement, Spread the Word ------------------------------------ - -Sometimes, a nice word, simple encouragement, and interest in the work -we're doing is enough to inspire a tizzy of productive work. Just a -bit more interest and encouragement can even make the difference -between a complete feature and limited functionality; between a -completed milestone and lost momentum. - -Similarly, MediaGoblin, and the movement for free network services, is -always in need of encouragement. Use free network services, understand -the `principals `_ -behind the movement, be able to articulate the benefits of free -network services and the problems with psudo-free applications that -don't respect the users' freedom. - -Write a blog post, post a status update, drop by the `listserv `_ -or join ``#mediagoblin`` on freenode.net and let us know. - -Participate in MediaGoblin -========================== - -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 Others ------------ - -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 MediaGoblin 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 -the `Deployment HOWTO `_ - -.. _translating: - -Translate MediaGoblin ---------------------- - -If you know English and another language and feel comfortable -translating elements of the interface or even the documentation, -we'd love to have help translating the software and resources. - -Create a Theme --------------- - -MedaGoblin development is premised on the idea that the entire -interface for the platform be completely theme-able. If you have a -design or theming background, consider developing themes for -MediaGoblin. New themes help test the theming system, provide -attractive and appealing interfaces for prospective users. If you want -to start a new theme but don't know where to start, touch base with -the development community on the list or in the IRC channel for more -information. - -.. _filing-bugs: - -File Bugs -========= - -MediaGoblin uses a bug tracker called `Redmine `_. - -Our instance is located at ``_. - -The most useful bug reports have the following components: - -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. Consider: - - * If you think you've found a bug, can you reproduce it in a - controlled environment? Is the issue specific to a browser, - computer, image, media type, or other dimension? All data helps. - - * If you're submitting 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! - -The better the issue report, the easier it is to address the bug, and -the more likely that the developers will be able to resolve the -issue. If someone has questions about the bug report, they may reach -out to the reporter directly. - -If you get a response after a couple of weeks, find someone on IRC. - -.. _triage-bugs: - -Triage Bugs -=========== - -The triage process involves reviewing bugs, removing duplicates, -validating that the issues described are reproducible, ensuring that -the exact behavior is properly documented, diagnosing the cause of -each issue, and working with developers to ensure that critical bugs -get addressed. In many cases, developers do this kind of work as a -matter of course, but one need not be able to code in order to help -working with bugs. - -To triage bugs, go to the `bug tracker `_ -and begin reviewing the open issues. If you are able, attempt to: - -- ensure that one or two people in addition to the initial reporter - have been able to reproduce the issue. - -- document the issue more clearly. If you had any trouble reproducing - the issue, provide any elucidating information that you can to help - others solve the problem more effectively. - -- find a way to resolve the problem or provide a workaround. - -For help, instructions, and suggestions be in touch with the -development community on the list or in the IRC channel for more -information. With many eyes, all bugs are shallow. - -How to Get Help with MediaGoblin -================================ - -The usual channels, the IRC channel, the listserv, the bug tracker, -are all great ways to be in touch with us. Check the `web site `_ -for more specific contact information. - diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst new file mode 100644 index 00000000..db92257a --- /dev/null +++ b/docs/source/deploying.rst @@ -0,0 +1,16 @@ +.. _deployment-chapter: + +======================= + Deploying MediaGoblin +======================= + +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 on +`the wiki `_. diff --git a/docs/source/deploymenthowto.rst b/docs/source/deploymenthowto.rst deleted file mode 100644 index f3093a60..00000000 --- a/docs/source/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 on -`the wiki `_. diff --git a/docs/source/foreword.rst b/docs/source/foreword.rst index c525d002..835a7e7a 100644 --- a/docs/source/foreword.rst +++ b/docs/source/foreword.rst @@ -5,25 +5,15 @@ Foreword About the MediaGoblin Manual ============================ -Welcome to the GNU MediaGoblin manual. This document targets several -classes of users, including: +This is the user manual for MediaGoblin. It covers how to set up and +configure MediaGoblin and the kind of information that someone running +MediaGoblin would need to know. -* users who would like to try the software locally, -* systems administrators who want to deploy and administer the - software in "production environments," and -* anyone who wants to learn how MediaGoblin works. +We have other documentation at: -Some information relevant to the MediaGoblin community members, -including how to get involved (We want and love contributors!) To join -as a contributor please see the following pages: - -* http://mediagoblin.org/pages/join.html for general "join us" information +* http://mediagoblin.org/join/ for general "join us" information * http://wiki.mediagoblin.org/ for our contributor-focused wiki -If you suspect that documentation on http://docs.mediagoblin.org is -out of date, it might be. The documentation is updated regularly and -the "living" version of this resource resides in the ``mediagoblin`` -repository with the project's source code the ``docs/`` directory. Improving the MediaGobiin Manual ================================ @@ -31,16 +21,15 @@ Improving the MediaGobiin Manual There are a few ways---please pick whichever method is convenient for you! -1. Write up a bug report in the bug tracker at http://bugs.foocorp.net/projects/mediagoblin/issues +1. Write up a bug report in the bug tracker 2. Tell someone on IRC ``#mediagoblin`` on Freenode. -3. Send an email to Will ``willg at bluesock dot org``, or Sam at - ``sam@cyborginstitute.com`` +3. Write an email to the devel mailing list. + +Information about the bugtracker, IRC and the mailing list is all on +the `join page`_. -When you tell us about your issue, please let us know: +.. _join page: http://mediagoblin.org/join/ -* where you are looking (in git? url of the web-page?) -* what the issue is, and -* your thoughts on how to resolve it. +Patches are the most helpful, but even feedback on what you think +could be improved and how to improve it is also helpful. -We hope these materials are useful and we look forward to any and all -feedback. diff --git a/docs/source/help.rst b/docs/source/help.rst new file mode 100644 index 00000000..34d4f37e --- /dev/null +++ b/docs/source/help.rst @@ -0,0 +1,16 @@ +================================== + How to Get Help with MediaGoblin +================================== + +There are a couple of ways to get help with problems with MediaGoblin: + +1. ask for help on IRC + +2. ask for help on the devel mailing list + +Details for both IRC and the mailing list are on the `join page`_ of the +website. + +.. _join page: http://mediagoblin.org/join/ + + diff --git a/docs/source/index.rst b/docs/source/index.rst index 93b2a942..088b5359 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,12 +12,11 @@ Table of Contents: :maxdepth: 2 foreword - about_mediagoblin - deploymenthowto - theminghowto - contributinghowto + about + deploying + help + theming codebase - vision Indices and tables diff --git a/docs/source/theming.rst b/docs/source/theming.rst new file mode 100644 index 00000000..2f4fcb4c --- /dev/null +++ b/docs/source/theming.rst @@ -0,0 +1,8 @@ +.. _theming-chapter: + +===================== + Theming MediaGoblin +===================== + +We haven't implemented the necessary scaffolding to allow for theming +yet. Thus, this chapter is a stub. diff --git a/docs/source/theminghowto.rst b/docs/source/theminghowto.rst deleted file mode 100644 index 7b40685f..00000000 --- a/docs/source/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/source/vision.rst b/docs/source/vision.rst deleted file mode 100644 index fad248df..00000000 --- a/docs/source/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 e260065ae543885a80ca98dcc3394e763c80d007 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 30 Oct 2011 11:55:41 -0500 Subject: Added a lot more details to deploying.rst --- docs/source/deploying.rst | 107 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 100 insertions(+), 7 deletions(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index db92257a..b35d72d2 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -4,13 +4,106 @@ Deploying MediaGoblin ======================= -Step 1: Write code that can be deployed. +GNU MediaGoblin is fairly new and so at the time of writing, there +aren't easy package-manager-friendly methods to install MediaGoblin. +However, doing a basic install isn't too complex in and of itself. -Step 2: ? +There's an almost infinite way to deploy things... for now, we'll keep +it simple with some assumptions and use a setup that combines +mediagoblin + virtualenv + fastcgi + nginx on a .deb or .rpm based +GNU/Linux distro. + +Note: these tools are for administrators wanting to deploy a fresh +install. If instead you want to join in as a contributor, see our +`Hacking HOWTO `_ instead. + +Install dependencies +==================== + +First thing you want to do is install necessary dependencies. Those +are, roughly: + + - Python 2.6 or 2.7 + - python-lxml - http://lxml.de/ + - git - http://git-scm.com/ + - MongoDB - http://www.mongodb.org/ + - Python Imaging Library (PIL) - http://www.pythonware.com/products/pil/ + - virtualenv - http://www.virtualenv.org/ + +On a .deb based system (Debian, GnewSense, Trisquel, Ubuntu, etc) run +the following: + + sudo apt-get install mongodb git-core python python-dev \ + python-lxml python-imaging python-virtualenv + +On a .rpm based system (Fedora, RedHat, etc): + + yum install mongodb-server python-paste-deploy python-paste-script \ + git-core python python-devel python-lxml python-imaging python-virtualenv + +Configure MongoDB +================= + +So you have MongoDB installed... you should probably make sure that +you have a few things configured before you start up MediaGoblin. + +For one thing, you almost certainly want to make sure `journaling +`_ is enabled. +Journaling is automatically enabled on 64 bit systems post-MongoDB +2.0, but you should check. (Not turning on journaling means that if +your server crashes you have a good chance of losing data!) + +MongoDB can take a lot of space by default. If you're planning on +running a smaller instance, consider following our `scaling down +`_ guide (keeping in mind +that the steps recommended here are tradeoffs!). + +Install MediaGoblin and Virtualenv +================================== + +For the moment, let's assume you want to run the absolute most +bleeding edge version of mediagoblin in mediagoblin master (possibly +not the best choice in a production environment, so these docs should +be fixed ;)). + +Clone the repository: + + git clone git://gitorious.org/mediagoblin/mediagoblin.git + +And setup the in-package virtualenv: + + virtualenv . && ./bin/python setup.py develop + +(If you have problems here, consider trying to install virtualenv with +one of the flags --distribute or --no-site-packages... Additionally if +your system has python3.X as the default you might need to do +virtualenv --python=python2.7 or --python=python2.6) + +(You might note that we've done an in-package install of +virtualenv... this isn't the most traditional way to install +virtualenv, and it might not even be the best. But it's the easiest +to explain without having to explain python packaging, and it works.) + +At this point your development environment should be setup. You don't +need to do anything else. However if at any point you update your +codebase, you should also run: + + ./bin/python setup.py develop --upgrade && ./bin/gmg migrate. + + +Test-start the server +===================== + +At this point mediagoblin should be properly installed. You can +test-start it like so: + + ./lazyserver.sh --server-name=broadcast + +You should be able to connect to the machine on port 6543 in your +browser to ensure that things are working. + + +Hook up to your webserver via fastcgi +===================================== -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 on -`the wiki `_. -- cgit v1.2.3 From 94011579e78ff4fdec12d8777ae3b06212aa517b Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 30 Oct 2011 16:07:48 -0500 Subject: Hook mediagoblin up to nginx --- docs/source/deploying.rst | 80 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index b35d72d2..e2f13c07 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -72,6 +72,7 @@ Clone the repository: And setup the in-package virtualenv: + cd mediagoblin virtualenv . && ./bin/python setup.py develop (If you have problems here, consider trying to install virtualenv with @@ -106,4 +107,83 @@ browser to ensure that things are working. Hook up to your webserver via fastcgi ===================================== +This section describes how to configure MediaGoblin to work via +fastcgi. Our configuration example will use nginx, as the author of +this manual feels that nginx config files are easier to understand if +you have no experience with any type of configuration file. However, +the translations to apache are not too hard. + +Also for the sake of this document, we'll assume you're running +mediagoblin on the domain mediagoblin.example.org and your +mediagoblin checkout in /var/www/mediagoblin.example.org/mediagoblin/ + +Now in reality, you won't be running mediagoblin on such a domain or +in such a directory, but it should be easy enough to move your stuff +over. + +Anyway, in such an environment, make a config file in the normal place +you'd make such an nginx config file... probably +/etc/nginx/sites-available/mediagoblin.example.conf (and symlink said +file over to /etc/nginx/sites-enabled/ to turn it on) + +Now put in that file: + + server { + ################################################# + # Stock useful config options, but ignore them :) + ################################################# + server_name mediagoblin.example.org www.mediagoblin.example.org; + include /etc/nginx/mime.types; + + access_log /var/log/nginx/mediagoblin.example.access.log; + error_log /var/log/nginx/mediagoblin.example.error.log; + + autoindex off; + default_type application/octet-stream; + sendfile on; + # tcp_nopush on; + + # Gzip + gzip on; + gzip_min_length 1024; + gzip_buffers 4 32k; + gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; + + ##################################### + # Mounting MediaGoblin stuff + # This is the section you should read + ##################################### + + # MediaGoblin's stock static files: CSS, JS, etc. + location /mgoblin_static/ { + alias /var/www/mediagoblin.example.org/mediagoblin/static/; + } + + # Instance specific media: + location /mgoblin_media/ { + alias /var/www/mediagoblin.example.org/mediagoblin/user_dev/media/public/; + } + + # Mounting MediaGoblin itself via fastcgi. + location / { + fastcgi_pass 127.0.0.1:26543; + include /etc/nginx/fastcgi_params; + } + } + +At this point your config file should be properly set up to handle +serving mediagoblin. Now all you need to do is run it! + +Let's do a quick test. Restart nginx so it picks up your changes, +something probably like: + + sudo /etc/init.d/nginx restart + +Now start up MediaGoblin. "cd" to the MediaGoblin checkout and run: + + ./lazyserver.sh --server-name=http http_host=127.0.0.1 http_port=26543 + +Visit the site you've set up in your browser, eg +http://example.mediagoblin.org (except with the real domain name or IP +you're expecting to use. ;)) -- cgit v1.2.3 From 36dc2eaa661870cba1dd9ed50bc2bd09c8daa7cc Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 30 Oct 2011 16:22:35 -0500 Subject: If I"m telling people to use fastcgi, we should probably use fastcgi ;) --- docs/source/deploying.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index e2f13c07..ca3d5046 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -181,7 +181,7 @@ something probably like: Now start up MediaGoblin. "cd" to the MediaGoblin checkout and run: - ./lazyserver.sh --server-name=http http_host=127.0.0.1 http_port=26543 + ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 Visit the site you've set up in your browser, eg http://example.mediagoblin.org (except with the real domain name or IP -- cgit v1.2.3 From 26e789eb0cf8a8d55fd43e0fea8d3c15f6fa8f64 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 30 Oct 2011 16:43:12 -0500 Subject: Let's comply with the Filesystem Hierarchy Standard ... and make elrond and tychoish happy :) --- docs/source/deploying.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index ca3d5046..22311a56 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -115,7 +115,7 @@ the translations to apache are not too hard. Also for the sake of this document, we'll assume you're running mediagoblin on the domain mediagoblin.example.org and your -mediagoblin checkout in /var/www/mediagoblin.example.org/mediagoblin/ +mediagoblin checkout in /srv/mediagoblin.example.org/mediagoblin/ Now in reality, you won't be running mediagoblin on such a domain or in such a directory, but it should be easy enough to move your stuff @@ -156,12 +156,12 @@ Now put in that file: # MediaGoblin's stock static files: CSS, JS, etc. location /mgoblin_static/ { - alias /var/www/mediagoblin.example.org/mediagoblin/static/; + alias /srv/mediagoblin.example.org/mediagoblin/static/; } # Instance specific media: location /mgoblin_media/ { - alias /var/www/mediagoblin.example.org/mediagoblin/user_dev/media/public/; + alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; } # Mounting MediaGoblin itself via fastcgi. -- cgit v1.2.3 From 17c712307dcff26226365ef856a71f9c1daeeeba Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 30 Oct 2011 16:47:39 -0500 Subject: Recommend that users use a non-privelaged user (thanks Elrond for the text) --- docs/source/deploying.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 22311a56..2e599b5e 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -58,6 +58,24 @@ running a smaller instance, consider following our `scaling down `_ guide (keeping in mind that the steps recommended here are tradeoffs!). + +Decide on a non-privileged user +=============================== + +As MediaGoblin does not require any special permissions, you +should either decide on a user to run it as, or even better create a +dedicated user for it. Consult your distribution's documentation on +how to create dedicated service user. Make sure it does have a locked +password, so nobody can login using this user. + +You should create a working dir for MediaGoblin. We assume you will +check things out into /srv/mediagoblin.example.org/mediagoblin/ for +this documentation, but you can choose whatever fits your local needs. + +Most of the remaining documentation assumes you're working as that +user. As root, you might want to do "su - mediagoblinuser". + + Install MediaGoblin and Virtualenv ================================== @@ -66,6 +84,10 @@ bleeding edge version of mediagoblin in mediagoblin master (possibly not the best choice in a production environment, so these docs should be fixed ;)). +Change to (and possibly make) the appropriate parent directory: + + cd /srv/mediagoblin.example.org/ + Clone the repository: git clone git://gitorious.org/mediagoblin/mediagoblin.git -- cgit v1.2.3 From 80bcaa5cb1d2d0cbd419c81cd7ca3b7970817368 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 30 Oct 2011 16:59:15 -0500 Subject: No reason to include commented-out things. --- docs/source/deploying.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 2e599b5e..0aece001 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -163,7 +163,6 @@ Now put in that file: autoindex off; default_type application/octet-stream; sendfile on; - # tcp_nopush on; # Gzip gzip on; -- cgit v1.2.3 From 2f9bd4d4582a938bc138b92789fcb9ff3fb44a50 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 30 Oct 2011 18:59:07 -0500 Subject: Added notes on a more permanent mediagoblin process. --- docs/source/deploying.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 0aece001..69478277 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -208,3 +208,25 @@ Visit the site you've set up in your browser, eg http://example.mediagoblin.org (except with the real domain name or IP you're expecting to use. ;)) + +A more permanent mediagoblin process via paste +============================================== + +At this point, you probably have a MediaGoblin instance that for most +intents and purposes works, but lazyserver is... well, lazy. You +probably want to set up a process that you can launch in init scripts. + +Try something along the lines of: + + CELERY_ALWAYS_EAGER=true \ + /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ + /srv/mediagoblin.example.org/mediagoblin/paste.ini \ + --pid-file=/tmp/mediagoblin.pid \ + --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ + +Feel free to adjust any of this. + +Note that this runs MediaGoblin in "always eager" mode with Celery. +This is fine for development and smaller deployments. However if +you're getting into the really large deployment category, consider +reading the section of this manual on Celery. -- cgit v1.2.3 From 4e893b6ea1b9ab4d9a104d9a3a0751598bb3c8f5 Mon Sep 17 00:00:00 2001 From: tycho garen Date: Mon, 31 Oct 2011 00:21:30 -0400 Subject: docs: editing/tweaking deployment documentation --- docs/source/deploying.rst | 380 ++++++++++++++++++++++++---------------------- 1 file changed, 201 insertions(+), 179 deletions(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 69478277..5f07a1d2 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -1,8 +1,6 @@ -.. _deployment-chapter: - -======================= - Deploying MediaGoblin -======================= +===================== +Deploying MediaGoblin +===================== GNU MediaGoblin is fairly new and so at the time of writing, there aren't easy package-manager-friendly methods to install MediaGoblin. @@ -17,216 +15,240 @@ Note: these tools are for administrators wanting to deploy a fresh install. If instead you want to join in as a contributor, see our `Hacking HOWTO `_ instead. -Install dependencies -==================== +Prepare System +-------------- -First thing you want to do is install necessary dependencies. Those -are, roughly: +Dependencies +~~~~~~~~~~~~ - - Python 2.6 or 2.7 - - python-lxml - http://lxml.de/ - - git - http://git-scm.com/ - - MongoDB - http://www.mongodb.org/ - - Python Imaging Library (PIL) - http://www.pythonware.com/products/pil/ - - virtualenv - http://www.virtualenv.org/ +MediaGoblin has the following core dependencies: -On a .deb based system (Debian, GnewSense, Trisquel, Ubuntu, etc) run -the following: +- Python 2.6 or 2.7 +- `python-lxml `_ +- `git `_ +- `MongoDB `_ +- `Python Imaging Library `_ (PIL) +- `virtualenv `_ - sudo apt-get install mongodb git-core python python-dev \ - python-lxml python-imaging python-virtualenv +On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and +derivatives) issue the following command: :: -On a .rpm based system (Fedora, RedHat, etc): + sudo apt-get install mongodb git-core python python-dev python-lxml python-imaging python-virtualenv - yum install mongodb-server python-paste-deploy python-paste-script \ - git-core python python-devel python-lxml python-imaging python-virtualenv +On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the +following command: :: + + yum install mongodb-server python-paste-deploy python-paste-script git-core python python-devel python-lxml python-imaging python-virtualenv Configure MongoDB -================= +~~~~~~~~~~~~~~~~~ + +After installing MongoDB some preliminary database configuration may +be necessary. + +Ensure that MongoDB `journaling `_ +is enabled. Journaling is enabled by default in version 2.0 and later +64-bit MongoDB instances. Check your deployment, and consider enabling +journaling if you're running 32-bit systems or earlier version. -So you have MongoDB installed... you should probably make sure that -you have a few things configured before you start up MediaGoblin. +.. warning:: -For one thing, you almost certainly want to make sure `journaling -`_ is enabled. -Journaling is automatically enabled on 64 bit systems post-MongoDB -2.0, but you should check. (Not turning on journaling means that if -your server crashes you have a good chance of losing data!) + Running MongoDB without journaling risks general data corruption + and raises the possibility of losing data within a 60-second + window when the server restarts. -MongoDB can take a lot of space by default. If you're planning on -running a smaller instance, consider following our `scaling down -`_ guide (keeping in mind -that the steps recommended here are tradeoffs!). + MediaGoblin recommends enabling MongoDB's journaling feature by + adding a ``--journal`` flag to the command line or a "``journal: + true``" option to the configuration file. +MongoDB can take a lot of space by default. If you're planning on +running a smaller instance, consider the `scaling down guide +`_ for some appropriate +tradeoffs to conserve space. -Decide on a non-privileged user -=============================== +Drop Privileges for MediaGoblin +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -As MediaGoblin does not require any special permissions, you -should either decide on a user to run it as, or even better create a -dedicated user for it. Consult your distribution's documentation on -how to create dedicated service user. Make sure it does have a locked -password, so nobody can login using this user. +As MediaGoblin does not require special permissions or elevated +access, you should run MediaGoblin under an existing non-root user or +preferably create a dedicated user for the purpose of running +MediaGoblin. Consult your distribution's documentation on how to +create "system account" or dedicated service user. Ensure that it is +not possible to log in to your system with as this user. -You should create a working dir for MediaGoblin. We assume you will -check things out into /srv/mediagoblin.example.org/mediagoblin/ for -this documentation, but you can choose whatever fits your local needs. +You should create a working directory for MediaGoblin. This document +assumes your local git repository will be located at ``/srv/mediagoblin.example.org/mediagoblin/`` +for this documentation. Substitute your prefer ed local deployment path +as needed. -Most of the remaining documentation assumes you're working as that -user. As root, you might want to do "su - mediagoblinuser". +This document assumes that all operations are performed as this +user. To drop privileges to this user, run the following command: :: + su - [mediagoblin]`` + +Where, "``[mediagoblin]`` is the username of the system user that will +run MediaGoblin. + Install MediaGoblin and Virtualenv -================================== +---------------------------------- -For the moment, let's assume you want to run the absolute most -bleeding edge version of mediagoblin in mediagoblin master (possibly -not the best choice in a production environment, so these docs should -be fixed ;)). +As of |version|, MediaGoblin has a rapid development pace. As a result +the following instructions recommend installing from the ``master`` +branch of the git repository. Eventually production deployments will +want to transition to running from more consistent releases. -Change to (and possibly make) the appropriate parent directory: +Issue the following commands, to create and change the working +directory. Modify these commands to reflect your own environment: :: - cd /srv/mediagoblin.example.org/ + mkdir -p /srv/mediagoblin.example.org/ + cd /srv/mediagoblin.example.org/ -Clone the repository: +Clone the MediaGoblin repository: :: - git clone git://gitorious.org/mediagoblin/mediagoblin.git + git clone git://gitorious.org/mediagoblin/mediagoblin.git -And setup the in-package virtualenv: +And setup the in-package virtualenv: :: - cd mediagoblin - virtualenv . && ./bin/python setup.py develop + cd mediagoblin + virtualenv . && ./bin/python setup.py develop -(If you have problems here, consider trying to install virtualenv with -one of the flags --distribute or --no-site-packages... Additionally if -your system has python3.X as the default you might need to do -virtualenv --python=python2.7 or --python=python2.6) +.. note:: -(You might note that we've done an in-package install of -virtualenv... this isn't the most traditional way to install -virtualenv, and it might not even be the best. But it's the easiest -to explain without having to explain python packaging, and it works.) + If you have problems here, consider trying to install virtualenv + with the ``--distribute`` or ``--no-site-packages`` options. If + your system's default Python is in the 3.x series you man need to + run ``virtualenv`` with the ``--python=python2.7`` or + ``--python=python2.6`` options. -At this point your development environment should be setup. You don't -need to do anything else. However if at any point you update your -codebase, you should also run: +The above provides an in-package install of ``virtualenv``. While this +is counter to the conventional ``virtualenv`` configuration, it is +more reliable and considerably easier to configure and illustrate. If +you're familiar with Python packaging you may consider deploying with +your preferred the method. - ./bin/python setup.py develop --upgrade && ./bin/gmg migrate. +This concludes the initial configuration of the development +environment. In the future, if at any point you want update your +codebase, you should also run: :: + ./bin/python setup.py develop --upgrade && ./bin/gmg migrate. -Test-start the server -===================== +Deploy MediaGoblin Services +--------------------------- -At this point mediagoblin should be properly installed. You can -test-start it like so: +Test the Server +~~~~~~~~~~~~~~~ - ./lazyserver.sh --server-name=broadcast +At this point MediaGoblin should be properly installed. You can +test the deployment with the following command: :: -You should be able to connect to the machine on port 6543 in your -browser to ensure that things are working. + ./lazyserver.sh --server-name=broadcast +You should be able to connect to the machine on port 6543 in your +browser to confirm that the service is operable. -Hook up to your webserver via fastcgi -===================================== +Connect the Webserver to MediaGoblin with FastCGI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section describes how to configure MediaGoblin to work via -fastcgi. Our configuration example will use nginx, as the author of -this manual feels that nginx config files are easier to understand if -you have no experience with any type of configuration file. However, -the translations to apache are not too hard. - -Also for the sake of this document, we'll assume you're running -mediagoblin on the domain mediagoblin.example.org and your -mediagoblin checkout in /srv/mediagoblin.example.org/mediagoblin/ - -Now in reality, you won't be running mediagoblin on such a domain or -in such a directory, but it should be easy enough to move your stuff -over. - -Anyway, in such an environment, make a config file in the normal place -you'd make such an nginx config file... probably -/etc/nginx/sites-available/mediagoblin.example.conf (and symlink said -file over to /etc/nginx/sites-enabled/ to turn it on) - -Now put in that file: - - server { - ################################################# - # Stock useful config options, but ignore them :) - ################################################# - server_name mediagoblin.example.org www.mediagoblin.example.org; - include /etc/nginx/mime.types; - - access_log /var/log/nginx/mediagoblin.example.access.log; - error_log /var/log/nginx/mediagoblin.example.error.log; - - autoindex off; - default_type application/octet-stream; - sendfile on; - - # Gzip - gzip on; - gzip_min_length 1024; - gzip_buffers 4 32k; - gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; - - ##################################### - # Mounting MediaGoblin stuff - # This is the section you should read - ##################################### - - # MediaGoblin's stock static files: CSS, JS, etc. - location /mgoblin_static/ { - alias /srv/mediagoblin.example.org/mediagoblin/static/; - } - - # Instance specific media: - location /mgoblin_media/ { - alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; - } - - # Mounting MediaGoblin itself via fastcgi. - location / { - fastcgi_pass 127.0.0.1:26543; - include /etc/nginx/fastcgi_params; - } - } - -At this point your config file should be properly set up to handle -serving mediagoblin. Now all you need to do is run it! - -Let's do a quick test. Restart nginx so it picks up your changes, -something probably like: - - sudo /etc/init.d/nginx restart - -Now start up MediaGoblin. "cd" to the MediaGoblin checkout and run: - - ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 - -Visit the site you've set up in your browser, eg -http://example.mediagoblin.org (except with the real domain name or IP -you're expecting to use. ;)) - - -A more permanent mediagoblin process via paste -============================================== - -At this point, you probably have a MediaGoblin instance that for most -intents and purposes works, but lazyserver is... well, lazy. You -probably want to set up a process that you can launch in init scripts. - -Try something along the lines of: - - CELERY_ALWAYS_EAGER=true \ - /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ - /srv/mediagoblin.example.org/mediagoblin/paste.ini \ - --pid-file=/tmp/mediagoblin.pid \ - --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ - -Feel free to adjust any of this. - -Note that this runs MediaGoblin in "always eager" mode with Celery. -This is fine for development and smaller deployments. However if -you're getting into the really large deployment category, consider -reading the section of this manual on Celery. +fastcgi. Our configuration example will use nginx, however, you may +use any webserver of your choice as long as it supports the FastCGI +protocol. If you do not already have a web server, consider nginx, as +the configuration files may be more clear than the +alternatives. + +Create a configuration file at +``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link +into a directory that will be included in your ``nginx`` configuration +(e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with +one of the following commands (as the root user:) :: + + ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/ + ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/ + +Modify these commands and locations depending on your preferences and +the existing configuration of your nginx instance. The contents of +this ``nginx.conf`` file should be modeled on the following: :: + + server { + ################################################# + # Stock useful config options, but ignore them :) + ################################################# + include /etc/nginx/mime.types; + + autoindex off; + default_type application/octet-stream; + sendfile on; + + # Gzip + gzip on; + gzip_min_length 1024; + gzip_buffers 4 32k; + gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; + + ##################################### + # Mounting MediaGoblin stuff + # This is the section you should read + ##################################### + + server_name mediagoblin.example.org www.mediagoblin.example.org; + access_log /var/log/nginx/mediagoblin.example.access.log; + error_log /var/log/nginx/mediagoblin.example.error.log; + + # MediaGoblin's stock static files: CSS, JS, etc. + location /mgoblin_static/ { + alias /srv/mediagoblin.example.org/mediagoblin/static/; + } + + # Instance specific media: + location /mgoblin_media/ { + alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; + } + + # Mounting MediaGoblin itself via fastcgi. + location / { + fastcgi_pass 127.0.0.1:26543; + include /etc/nginx/fastcgi_params; + } + } + +Now, nginx instance is configured to serve the MediaGoblin +application. Perform a quick test to ensure that this configuration +works. Restart nginx so it picks up your changes, with a command that +resembles one of the following (as the root user:) :: + + sudo /etc/init.d/nginx restart + sudo /etc/rc.d/nginx restart + +Now start MediaGoblin. Use the following command sequence as an +example: :: + + cd /srv/mediagoblin.example.org/mediagoblin/ + ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 + +Visit the site you've set up in your browser by visiting +. You should see MediaGoblin! + +Production MediaGoblin Deployments with Paste +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The instance configured with ``lazyserver`` is not ideal for a +production MediaGoblin deployment. Ideally, you should be able to use +a a control script (i.e. init script.) to launch and restart the +MediaGoblin process. + +Use the following command as the basis for such a script: :: + + CELERY_ALWAYS_EAGER=true \ + /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ + /srv/mediagoblin.example.org/mediagoblin/paste.ini \ + --pid-file=/tmp/mediagoblin.pid \ + --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ + +.. note:: + + The above configuration places MediaGoblin in "always eager" mode + with Celery. This is fine for development and smaller + deployments. However, if you're getting into the really large + deployment category, consider reading the section of this manual on + Celery. -- cgit v1.2.3 From ccff46ab4001f18173fbb55f5664cd905fae4608 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 30 Oct 2011 23:29:06 -0500 Subject: Configuring MediaGoblin, a loose sketch of documentation. --- docs/source/configuration.rst | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/source/configuration.rst (limited to 'docs/source') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst new file mode 100644 index 00000000..93cc4a17 --- /dev/null +++ b/docs/source/configuration.rst @@ -0,0 +1,38 @@ +.. _configuration-chapter: + +======================== +Configuring MediaGoblin +======================== + +So! You've got MediaGoblin up and running, but you need to adjust +some configuration parameters. Well you've come to the right place! + +MediaGoblin's config files +========================== + +When configuring MediaGoblin, there are two files you might want to +make local modified versions of, and one extra file that might be +helpful to look at. Let's examine these. + +mediagoblin.ini + The config file for MediaGoblin, the application. If you want to + tweak settings for MediaGoblin, you'll usually tweak them here. + +paste.ini + +mediagoblin.ini + + +Making local copies +=================== + + +Common changes +============== + + +Celery +====== + +We should point to another celery-specific section of the document +actually :) -- cgit v1.2.3 From 9205872e5a049a03c90494486b54c0424d8d1682 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 31 Oct 2011 21:58:21 -0500 Subject: First section of configuring mediagoblin --- docs/source/configuration.rst | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 93cc4a17..354a7098 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -19,8 +19,25 @@ mediagoblin.ini tweak settings for MediaGoblin, you'll usually tweak them here. paste.ini - -mediagoblin.ini + Primarily a server configuration file, on the python side + (specifically, on the wsgi side, via `paste deploy + `_ / `paste script + `_). It also sets up some + middleware that you can mostly ignore, except to configure + sessions... more on that later. If you are adding a different + python server other than fastcgi / plain http, you might configure + it here. Mostly you won't touch this file as much, probably. + + +There's one more file that you certainly won't change unless you're +making coding contributions to mediagoblin, but which can be useful to +read and reference: + +mediagoblin/config_spec.ini + This file is actually a specification for mediagoblin.ini itself, as + a config file! It defines types and defaults. Sometimes it's a + good place to look for documentation... or to find out that hidden + option that we didn't tell you about. :) Making local copies -- cgit v1.2.3 From 07913ec999a05f4b347f8abf35a54549a18d9262 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 31 Oct 2011 22:07:12 -0500 Subject: Added the "making local copies" section to configuration.rst --- docs/source/configuration.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'docs/source') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 354a7098..040b926d 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -43,6 +43,23 @@ mediagoblin/config_spec.ini Making local copies =================== +Assuming you're doing the virtualenv setup described elsewhere in this +manual and you need to make local tweaks to the config files, there's +an easy way to do that. + +To make changes to mediagoblin.ini: + + cp mediagoblin.ini mediagoblin_local.ini + +To make changes to paste.ini: + cp paste.ini paste_local.ini + +From here you should be able to make direct adjustments to the files, +and most of the commands described elsewhere in this manual will "notice" +your local config files and use those instead of the non-local version. + +(Note that all commands provide a way to pass in a specific config +file also, usually by a -cf flag.) Common changes ============== -- cgit v1.2.3 From 506f1f07aeee67d06fe7ffdda00bcdd442b8e864 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 31 Oct 2011 22:08:30 -0500 Subject: Making docs changes per Jim's suggestions. --- docs/source/configuration.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 040b926d..0d8bf5ec 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -15,18 +15,18 @@ make local modified versions of, and one extra file that might be helpful to look at. Let's examine these. mediagoblin.ini - The config file for MediaGoblin, the application. If you want to + This is the config file for MediaGoblin, the application. If you want to tweak settings for MediaGoblin, you'll usually tweak them here. paste.ini - Primarily a server configuration file, on the python side + This is primarily a server configuration file, on the python side (specifically, on the wsgi side, via `paste deploy `_ / `paste script `_). It also sets up some middleware that you can mostly ignore, except to configure sessions... more on that later. If you are adding a different python server other than fastcgi / plain http, you might configure - it here. Mostly you won't touch this file as much, probably. + it here. You probably won't need to change this file very much. There's one more file that you certainly won't change unless you're -- cgit v1.2.3 From 49fca84b9f508b677ed8a339667ffbffec498bd4 Mon Sep 17 00:00:00 2001 From: Jim Campbell Date: Mon, 31 Oct 2011 22:20:00 -0500 Subject: docs - tweaked configuration.rst for style. --- docs/source/configuration.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/source') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 0d8bf5ec..7eb61ec4 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -36,16 +36,16 @@ read and reference: mediagoblin/config_spec.ini This file is actually a specification for mediagoblin.ini itself, as a config file! It defines types and defaults. Sometimes it's a - good place to look for documentation... or to find out that hidden + good place to look for documentation... or to find that hidden option that we didn't tell you about. :) Making local copies =================== -Assuming you're doing the virtualenv setup described elsewhere in this -manual and you need to make local tweaks to the config files, there's -an easy way to do that. +Let's assume you're doing the virtualenv setup described elsewhere in this +manual, and you need to make local tweaks to the config files. How do you do +that? Let's see. To make changes to mediagoblin.ini: -- cgit v1.2.3 From 14fbfd18afc09ad5e1768d2604df340aeec09cc7 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 31 Oct 2011 22:26:47 -0500 Subject: Enabling email notifications documentation! --- docs/source/configuration.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'docs/source') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 0d8bf5ec..b6c55900 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -64,6 +64,28 @@ file also, usually by a -cf flag.) Common changes ============== +Enabling email notifications +---------------------------- + +You'll almost certainly want to enable sending emails. By default, +MediaGoblin doesn't really do this... for the sake of developer +convenience, it runs in "email debug mode". Change this: + + email_debug_mode = false + +You can (and should) change the "from" email address by setting +``email_sender_address``. + +Note that you need a mailer daemon running for this to work. + +If you have more custom SMTP settings, you also have the following +options at your disposal, which are all optional, and do exactly what +they sound like. + + - email_smtp_host + - email_smtp_port + - email_smtp_user + - email_smtp_pass Celery ====== -- cgit v1.2.3 From 28ce1d11533a8bfb14efa3de4004994f367b018f Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 31 Oct 2011 22:40:39 -0500 Subject: A cop-out section for all other config changes --- docs/source/configuration.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/source') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index b6c55900..38e712c9 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -87,6 +87,17 @@ they sound like. - email_smtp_user - email_smtp_pass +All other configuration changes +------------------------------- + +To be perfectly honest, there are quite a few options and I'm not +going to be able to get to documanting them all in time for 0.1.0. + +So here's a cop-out section saying that if you get into trouble, hop +onto IRC and we'll help you out: + + #mediagoblin on irc.freenode.net + Celery ====== -- cgit v1.2.3 From b31269d5976977662178ec20d83a2a78e60ce9df Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 31 Oct 2011 22:42:30 -0500 Subject: Added configuration to the index --- docs/source/index.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index 088b5359..e9f3993e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,6 +14,7 @@ Table of Contents: foreword about deploying + configuration help theming codebase -- cgit v1.2.3 From 8efddbf2986524ad777b671af9935b44d009103e Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 2 Nov 2011 09:09:35 -0500 Subject: 0.1.0, also in the docs file! ;) --- docs/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 7ea3a340..eee9900f 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.5' +version = '0.1.0' # The full version, including alpha/beta/rc tags. -release = '0.0.5' +release = '0.1.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From 99192f2452f75c0d8b0f04eefa0dd74f10e61e31 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 3 Nov 2011 09:41:48 -0500 Subject: Recommendation to install flup! --- docs/source/deploying.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 5f07a1d2..14665546 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -127,6 +127,11 @@ more reliable and considerably easier to configure and illustrate. If you're familiar with Python packaging you may consider deploying with your preferred the method. +Assuming you are going to deploy with fastcgi, you should also install +flup: :: + + ./bin/easy_install flup + This concludes the initial configuration of the development environment. In the future, if at any point you want update your codebase, you should also run: :: -- cgit v1.2.3 From a5d50276b9fa26859766d4e4b52240f3d8f55896 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 3 Nov 2011 10:23:53 -0500 Subject: We left out a critical fastcgi variable from the nginx config --- docs/source/deploying.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 14665546..61baddb8 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -213,6 +213,7 @@ this ``nginx.conf`` file should be modeled on the following: :: # Mounting MediaGoblin itself via fastcgi. location / { fastcgi_pass 127.0.0.1:26543; + fastcgi_param PATH_INFO $fastcgi_script_name; include /etc/nginx/fastcgi_params; } } -- cgit v1.2.3 From 996e9b4c4f6ad1ee8a03f5348a65895c88d040fe Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 3 Nov 2011 10:27:39 -0500 Subject: Indentation was off by one ;) --- docs/source/deploying.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 61baddb8..cbdf9a4c 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -213,7 +213,7 @@ this ``nginx.conf`` file should be modeled on the following: :: # Mounting MediaGoblin itself via fastcgi. location / { fastcgi_pass 127.0.0.1:26543; - fastcgi_param PATH_INFO $fastcgi_script_name; + fastcgi_param PATH_INFO $fastcgi_script_name; include /etc/nginx/fastcgi_params; } } -- cgit v1.2.3 From 02e99c78cdb91d3dab52675d11f29bf834e4f6ca Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 3 Nov 2011 10:59:47 -0500 Subject: A correct but compact set of instructions for fastcgi on nginx --- docs/source/deploying.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index cbdf9a4c..fbe829af 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -213,8 +213,12 @@ this ``nginx.conf`` file should be modeled on the following: :: # Mounting MediaGoblin itself via fastcgi. location / { fastcgi_pass 127.0.0.1:26543; - fastcgi_param PATH_INFO $fastcgi_script_name; include /etc/nginx/fastcgi_params; + + # our understanding vs nginx's handling of script_name vs + # path_info don't match :) + fastcgi_param PATH_INFO $fastcgi_script_name; + fastcgi_param SCRIPT_NAME ""; } } -- cgit v1.2.3 From baf03e9bf93483c474b5fcba379452071a8ae029 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 3 Nov 2011 17:10:39 -0500 Subject: Correcting the mediagoblin static/media aliases in the deployment guide --- docs/source/deploying.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index fbe829af..c2ba0c47 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -202,12 +202,12 @@ this ``nginx.conf`` file should be modeled on the following: :: # MediaGoblin's stock static files: CSS, JS, etc. location /mgoblin_static/ { - alias /srv/mediagoblin.example.org/mediagoblin/static/; + alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/; } # Instance specific media: location /mgoblin_media/ { - alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; + alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/user_dev/media/public/; } # Mounting MediaGoblin itself via fastcgi. -- cgit v1.2.3 From fc5695c538f2b6d230c0e431087e9c10e6deac6c Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sat, 19 Nov 2011 10:43:31 -0800 Subject: incorrect path in nginx config --- docs/source/deploying.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index c2ba0c47..b944a3d3 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -207,7 +207,7 @@ this ``nginx.conf`` file should be modeled on the following: :: # Instance specific media: location /mgoblin_media/ { - alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/user_dev/media/public/; + alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; } # Mounting MediaGoblin itself via fastcgi. -- cgit v1.2.3 From b25b00d26e41158591822f5570c15f1baf2bc30b Mon Sep 17 00:00:00 2001 From: tycho garen Date: Sun, 4 Dec 2011 14:51:00 -0500 Subject: DOCS: update to deployment documentation and new production deployments doc --- docs/source/deploying.rst | 10 +++---- docs/source/production-deployments.rst | 48 ++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 5 deletions(-) create mode 100644 docs/source/production-deployments.rst (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index b944a3d3..9c0acf30 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -244,7 +244,7 @@ Production MediaGoblin Deployments with Paste The instance configured with ``lazyserver`` is not ideal for a production MediaGoblin deployment. Ideally, you should be able to use -a a control script (i.e. init script.) to launch and restart the +a control script (i.e. init script.) to launch and restart the MediaGoblin process. Use the following command as the basis for such a script: :: @@ -252,13 +252,13 @@ Use the following command as the basis for such a script: :: CELERY_ALWAYS_EAGER=true \ /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ /srv/mediagoblin.example.org/mediagoblin/paste.ini \ - --pid-file=/tmp/mediagoblin.pid \ + --pid-file=/var/run/mediagoblin.pid \ --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ .. note:: The above configuration places MediaGoblin in "always eager" mode with Celery. This is fine for development and smaller - deployments. However, if you're getting into the really large - deployment category, consider reading the section of this manual on - Celery. + deployments. However, for larger production deployments with larger + processing requirements, see the ":doc:`production-deployments`" + documentation. diff --git a/docs/source/production-deployments.rst b/docs/source/production-deployments.rst new file mode 100644 index 00000000..37251734 --- /dev/null +++ b/docs/source/production-deployments.rst @@ -0,0 +1,48 @@ +========================================= +Considerations for Production Deployments +========================================= + +This document contains a number of suggestions for deploying +MediaGoblin in actual production environments. Consider +":doc:`deploying`" for a basic overview of how to deploy Media +Goblin. + +Celery +------ + +While the ``./lazyserer.sh`` configuration provides an efficient way to +start using a MediaGoblin instance, it is not suitable for production +deployments for several reasons: + +1. In nearly every scenario, work on the Celery queue will need to + balance with the demands of other processes, and cannot proceed + synchronously. This is a particularly relevant problem if you use + MediaGoblin to host Video content. + +2. Processing with Celery ought to be operationally separate from the + MediaGoblin application itself, this simplifies management and + support better workload distribution. + +3. ... additional reason here. .... + +Build an :ref:`init script ` around the following +command. + + CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd + +Modify your existing MediaGoblin and application init scripts, if +necessary, to prevent them from starting their own ``celeryd`` +processes. + +.. _init-script: + +Use an Init Script +------------------- + +TODO insert init script here + +Other Concerns +-------------- + +TODO What are they? + -- cgit v1.2.3 From 4752fdcf06764965d2f926d99f3831a968d8ea8d Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 4 Dec 2011 15:27:00 -0600 Subject: Filled in reason #3 to submit separate out celery. --- docs/source/production-deployments.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/production-deployments.rst b/docs/source/production-deployments.rst index 37251734..75acf9cf 100644 --- a/docs/source/production-deployments.rst +++ b/docs/source/production-deployments.rst @@ -23,7 +23,16 @@ deployments for several reasons: MediaGoblin application itself, this simplifies management and support better workload distribution. -3. ... additional reason here. .... +3. If your user submits something complex and it needs to process, + that's extra time your user has to sit around waiting when they + could get back immediately to doing things on the site. + Furthermore, if that processing step takes a long time, as it + certainly will for video, your user won't just be left waiting, + their connection will probably time out. + +Basically, if you're doing anything other than trivial images for a +small set of users (or something similarly trivial, like ascii art), +you want to switch over to doing a separate celery process. Build an :ref:`init script ` around the following command. -- cgit v1.2.3 From a085dda5d29a1353eaf7df3ddfc3a7c500af9186 Mon Sep 17 00:00:00 2001 From: tycho garen Date: Sun, 4 Dec 2011 17:06:54 -0500 Subject: DOCS:: #675 revision to deployment and production documents --- docs/source/deploying.rst | 25 ++-------- docs/source/index.rst | 1 + docs/source/production-deployments.rst | 83 ++++++++++++++++++++++------------ 3 files changed, 59 insertions(+), 50 deletions(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 9c0acf30..70b1a6af 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -239,26 +239,9 @@ example: :: Visit the site you've set up in your browser by visiting . You should see MediaGoblin! -Production MediaGoblin Deployments with Paste -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The instance configured with ``lazyserver`` is not ideal for a -production MediaGoblin deployment. Ideally, you should be able to use -a control script (i.e. init script.) to launch and restart the -MediaGoblin process. - -Use the following command as the basis for such a script: :: - - CELERY_ALWAYS_EAGER=true \ - /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ - /srv/mediagoblin.example.org/mediagoblin/paste.ini \ - --pid-file=/var/run/mediagoblin.pid \ - --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ - .. note:: - The above configuration places MediaGoblin in "always eager" mode - with Celery. This is fine for development and smaller - deployments. However, for larger production deployments with larger - processing requirements, see the ":doc:`production-deployments`" - documentation. + The configuration described above is sufficient for development and + smaller deployments. However, for larger production deployments + with larger processing requirements, see the + ":doc:`production-deployments`" documentation. diff --git a/docs/source/index.rst b/docs/source/index.rst index e9f3993e..6ffe0974 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,6 +14,7 @@ Table of Contents: foreword about deploying + production-deployments configuration help theming diff --git a/docs/source/production-deployments.rst b/docs/source/production-deployments.rst index 75acf9cf..7bf26169 100644 --- a/docs/source/production-deployments.rst +++ b/docs/source/production-deployments.rst @@ -7,32 +7,54 @@ MediaGoblin in actual production environments. Consider ":doc:`deploying`" for a basic overview of how to deploy Media Goblin. -Celery ------- +Deploy with Paste +----------------- + +The instance configured with ``./lazyserver.sh`` is not ideal for a +production MediaGoblin deployment. Ideally, you should be able to use +an "init" or "control" script to launch and restart the MediaGoblin +process. + +Use the following command as the basis for such a script: :: + + CELERY_ALWAYS_EAGER=true \ + /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ + /srv/mediagoblin.example.org/mediagoblin/paste.ini \ + --pid-file=/var/run/mediagoblin.pid \ + --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ + +The above configuration places MediaGoblin in "always eager" mode +with Celery, this means that submissions of content will be processed +synchronously, and the user will advance to the next page only after +processing is complete. If we take Celery out of "always eager mode," +the user will be able to immediately return to the MediaGoblin site +while processing is ongoing. In these cases, use the following command +as the basis for your script: :: + + CELERY_ALWAYS_EAGER=false \ + /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ + /srv/mediagoblin.example.org/mediagoblin/paste.ini \ + --pid-file=/var/run/mediagoblin.pid \ + --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ + +Separate Celery +--------------- While the ``./lazyserer.sh`` configuration provides an efficient way to start using a MediaGoblin instance, it is not suitable for production deployments for several reasons: -1. In nearly every scenario, work on the Celery queue will need to - balance with the demands of other processes, and cannot proceed - synchronously. This is a particularly relevant problem if you use - MediaGoblin to host Video content. +In nearly every scenario, work on the Celery queue will need to +balance with the demands of other processes, and cannot proceed +synchronously. This is a particularly relevant problem if you use +MediaGoblin to host video content. Processing with Celery ought to be +operationally separate from the MediaGoblin application itself, this +simplifies management and support better workload distribution. -2. Processing with Celery ought to be operationally separate from the - MediaGoblin application itself, this simplifies management and - support better workload distribution. - -3. If your user submits something complex and it needs to process, - that's extra time your user has to sit around waiting when they - could get back immediately to doing things on the site. - Furthermore, if that processing step takes a long time, as it - certainly will for video, your user won't just be left waiting, - their connection will probably time out. - -Basically, if you're doing anything other than trivial images for a -small set of users (or something similarly trivial, like ascii art), -you want to switch over to doing a separate celery process. +Basically, if you're doing anything beyond a trivial workload, such as +image hosting for a small set of users, or have limited media types +such as "ASCII art" or icon sharing, you will need to run ``celeryd`` +as a separate process. Build an :ref:`init script ` around the following command. @@ -46,12 +68,15 @@ processes. .. _init-script: Use an Init Script -------------------- - -TODO insert init script here - -Other Concerns --------------- - -TODO What are they? - +------------------ + +Look in your system's ``/etc/init.d/`` or ``/etc/rc.d/`` directory for +examples of how to build scripts that will start, stop, and restart +MediaGoblin and Celery. These scripts will vary by +distribution/operating system. In the future, MediaGoblin will provide +example scripts as examples. + +.. TODO insert init script here +.. TODO are additional concernts ? + .. Other Concerns + .. -------------- -- cgit v1.2.3 From 438dd8cd8f79f32609cce15d70ef6a93f1531a3b Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 12 Dec 2011 08:13:46 -0600 Subject: Add a note on how to up the upload size limit --- docs/source/deploying.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 70b1a6af..14b2c9cf 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -196,6 +196,9 @@ this ``nginx.conf`` file should be modeled on the following: :: # This is the section you should read ##################################### + # Change this to update the upload size limit for your users + client_max_body_size 8m; + server_name mediagoblin.example.org www.mediagoblin.example.org; access_log /var/log/nginx/mediagoblin.example.access.log; error_log /var/log/nginx/mediagoblin.example.error.log; -- cgit v1.2.3 From 076bf0cf28bae50dcd0f9e79e5c9e6501f1ad04a Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 12 Dec 2011 10:20:05 -0500 Subject: Doc updates * fixed some language * fixed some consistency issues * fixed some 80-line-width issues * fixed some typos and markup problems --- docs/source/configuration.rst | 42 +++---- docs/source/deploying.rst | 195 +++++++++++++++++---------------- docs/source/foreword.rst | 8 +- docs/source/production-deployments.rst | 29 +++-- 4 files changed, 142 insertions(+), 132 deletions(-) (limited to 'docs/source') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 093f492c..1e22ad2d 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -19,13 +19,13 @@ mediagoblin.ini tweak settings for MediaGoblin, you'll usually tweak them here. paste.ini - This is primarily a server configuration file, on the python side - (specifically, on the wsgi side, via `paste deploy + This is primarily a server configuration file, on the Python side + (specifically, on the WSGI side, via `paste deploy `_ / `paste script `_). It also sets up some middleware that you can mostly ignore, except to configure sessions... more on that later. If you are adding a different - python server other than fastcgi / plain http, you might configure + Python server other than fastcgi / plain HTTP, you might configure it here. You probably won't need to change this file very much. @@ -47,19 +47,23 @@ Let's assume you're doing the virtualenv setup described elsewhere in this manual, and you need to make local tweaks to the config files. How do you do that? Let's see. -To make changes to mediagoblin.ini: +To make changes to mediagoblin.ini :: - cp mediagoblin.ini mediagoblin_local.ini + cp mediagoblin.ini mediagoblin_local.ini -To make changes to paste.ini: - cp paste.ini paste_local.ini +To make changes to paste.ini :: + + cp paste.ini paste_local.ini From here you should be able to make direct adjustments to the files, and most of the commands described elsewhere in this manual will "notice" your local config files and use those instead of the non-local version. -(Note that all commands provide a way to pass in a specific config -file also, usually by a -cf flag.) +.. note:: + + Note that all commands provide a way to pass in a specific config + file also, usually by a ``-cf`` flag. + Common changes ============== @@ -69,9 +73,9 @@ Enabling email notifications You'll almost certainly want to enable sending emails. By default, MediaGoblin doesn't really do this... for the sake of developer -convenience, it runs in "email debug mode". Change this: +convenience, it runs in "email debug mode". Change this:: - email_debug_mode = false + email_debug_mode = false You can (and should) change the "from" email address by setting ``email_sender_address``. @@ -82,21 +86,21 @@ If you have more custom SMTP settings, you also have the following options at your disposal, which are all optional, and do exactly what they sound like. - - email_smtp_host - - email_smtp_port - - email_smtp_user - - email_smtp_pass +- email_smtp_host +- email_smtp_port +- email_smtp_user +- email_smtp_pass All other configuration changes ------------------------------- -To be perfectly honest, there are quite a few options and I'm not -going to be able to get to documanting them all in time for 0.1.0. +To be perfectly honest, there are quite a few options and we haven't had +time to document them all So here's a cop-out section saying that if you get into trouble, hop -onto IRC and we'll help you out: +onto IRC and we'll help you out:: - #mediagoblin on irc.freenode.net + #mediagoblin on irc.freenode.net Celery ====== diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 14b2c9cf..4aded2e6 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -11,9 +11,11 @@ it simple with some assumptions and use a setup that combines mediagoblin + virtualenv + fastcgi + nginx on a .deb or .rpm based GNU/Linux distro. -Note: these tools are for administrators wanting to deploy a fresh -install. If instead you want to join in as a contributor, see our -`Hacking HOWTO `_ instead. +.. note:: + + These tools are for site administrators wanting to deploy a fresh + install. If instead you want to join in as a contributor, see our + `Hacking HOWTO `_ instead. Prepare System -------------- @@ -33,12 +35,15 @@ MediaGoblin has the following core dependencies: On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and derivatives) issue the following command: :: - sudo apt-get install mongodb git-core python python-dev python-lxml python-imaging python-virtualenv + sudo apt-get install mongodb git-core python python-dev python-lxml \ + python-imaging python-virtualenv On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the following command: :: - yum install mongodb-server python-paste-deploy python-paste-script git-core python python-devel python-lxml python-imaging python-virtualenv + yum install mongodb-server python-paste-deploy python-paste-script \ + git-core python python-devel python-lxml python-imaging \ + python-virtualenv Configure MongoDB ~~~~~~~~~~~~~~~~~ @@ -46,10 +51,11 @@ Configure MongoDB After installing MongoDB some preliminary database configuration may be necessary. -Ensure that MongoDB `journaling `_ -is enabled. Journaling is enabled by default in version 2.0 and later -64-bit MongoDB instances. Check your deployment, and consider enabling -journaling if you're running 32-bit systems or earlier version. +Ensure that MongoDB `journaling +`_ is enabled. Journaling +is enabled by default in version 2.0 and later 64-bit MongoDB instances. +Check your deployment, and consider enabling journaling if you're running +32-bit systems or earlier version. .. warning:: @@ -77,41 +83,42 @@ create "system account" or dedicated service user. Ensure that it is not possible to log in to your system with as this user. You should create a working directory for MediaGoblin. This document -assumes your local git repository will be located at ``/srv/mediagoblin.example.org/mediagoblin/`` -for this documentation. Substitute your prefer ed local deployment path -as needed. +assumes your local git repository will be located at +``/srv/mediagoblin.example.org/mediagoblin/`` for this documentation. +Substitute your prefer ed local deployment path as needed. This document assumes that all operations are performed as this user. To drop privileges to this user, run the following command: :: + su - [mediagoblin] - su - [mediagoblin]`` - -Where, "``[mediagoblin]`` is the username of the system user that will +Where, "``[mediagoblin]``" is the username of the system user that will run MediaGoblin. Install MediaGoblin and Virtualenv ---------------------------------- -As of |version|, MediaGoblin has a rapid development pace. As a result -the following instructions recommend installing from the ``master`` -branch of the git repository. Eventually production deployments will -want to transition to running from more consistent releases. +.. note:: + + As of |version|, MediaGoblin has a rapid development pace. As a result + the following instructions recommend installing from the ``master`` + branch of the git repository. Eventually production deployments will + want to transition to running from more consistent releases. Issue the following commands, to create and change the working -directory. Modify these commands to reflect your own environment: :: +directory. Modify these commands to reflect your own environment:: - mkdir -p /srv/mediagoblin.example.org/ - cd /srv/mediagoblin.example.org/ + mkdir -p /srv/mediagoblin.example.org/ + cd /srv/mediagoblin.example.org/ -Clone the MediaGoblin repository: :: +Clone the MediaGoblin repository:: - git clone git://gitorious.org/mediagoblin/mediagoblin.git + git clone git://gitorious.org/mediagoblin/mediagoblin.git -And setup the in-package virtualenv: :: +And setup the in-package virtualenv:: - cd mediagoblin - virtualenv . && ./bin/python setup.py develop + cd mediagoblin + virtualenv . && ./bin/python setup.py develop .. note:: @@ -127,16 +134,16 @@ more reliable and considerably easier to configure and illustrate. If you're familiar with Python packaging you may consider deploying with your preferred the method. -Assuming you are going to deploy with fastcgi, you should also install -flup: :: +Assuming you are going to deploy with FastCGI, you should also install +flup:: - ./bin/easy_install flup + ./bin/easy_install flup This concludes the initial configuration of the development environment. In the future, if at any point you want update your -codebase, you should also run: :: +codebase, you should also run:: - ./bin/python setup.py develop --upgrade && ./bin/gmg migrate. + ./bin/python setup.py develop --upgrade && ./bin/gmg migrate. Deploy MediaGoblin Services --------------------------- @@ -145,9 +152,9 @@ Test the Server ~~~~~~~~~~~~~~~ At this point MediaGoblin should be properly installed. You can -test the deployment with the following command: :: +test the deployment with the following command:: - ./lazyserver.sh --server-name=broadcast + ./lazyserver.sh --server-name=broadcast You should be able to connect to the machine on port 6543 in your browser to confirm that the service is operable. @@ -156,7 +163,7 @@ Connect the Webserver to MediaGoblin with FastCGI ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section describes how to configure MediaGoblin to work via -fastcgi. Our configuration example will use nginx, however, you may +FastCGI. Our configuration example will use nginx, however, you may use any webserver of your choice as long as it supports the FastCGI protocol. If you do not already have a web server, consider nginx, as the configuration files may be more clear than the @@ -166,78 +173,78 @@ Create a configuration file at ``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link into a directory that will be included in your ``nginx`` configuration (e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with -one of the following commands (as the root user:) :: +one of the following commands (as the root user):: - ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/ - ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/ + ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/ + ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/ Modify these commands and locations depending on your preferences and the existing configuration of your nginx instance. The contents of -this ``nginx.conf`` file should be modeled on the following: :: - - server { - ################################################# - # Stock useful config options, but ignore them :) - ################################################# - include /etc/nginx/mime.types; - - autoindex off; - default_type application/octet-stream; - sendfile on; - - # Gzip - gzip on; - gzip_min_length 1024; - gzip_buffers 4 32k; - gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; - - ##################################### - # Mounting MediaGoblin stuff - # This is the section you should read - ##################################### - - # Change this to update the upload size limit for your users - client_max_body_size 8m; - - server_name mediagoblin.example.org www.mediagoblin.example.org; - access_log /var/log/nginx/mediagoblin.example.access.log; - error_log /var/log/nginx/mediagoblin.example.error.log; - - # MediaGoblin's stock static files: CSS, JS, etc. - location /mgoblin_static/ { - alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/; - } - - # Instance specific media: - location /mgoblin_media/ { - alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; - } - - # Mounting MediaGoblin itself via fastcgi. - location / { - fastcgi_pass 127.0.0.1:26543; - include /etc/nginx/fastcgi_params; - - # our understanding vs nginx's handling of script_name vs - # path_info don't match :) - fastcgi_param PATH_INFO $fastcgi_script_name; - fastcgi_param SCRIPT_NAME ""; - } +this ``nginx.conf`` file should be modeled on the following:: + + server { + ################################################# + # Stock useful config options, but ignore them :) + ################################################# + include /etc/nginx/mime.types; + + autoindex off; + default_type application/octet-stream; + sendfile on; + + # Gzip + gzip on; + gzip_min_length 1024; + gzip_buffers 4 32k; + gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; + + ##################################### + # Mounting MediaGoblin stuff + # This is the section you should read + ##################################### + + # Change this to update the upload size limit for your users + client_max_body_size 8m; + + server_name mediagoblin.example.org www.mediagoblin.example.org; + access_log /var/log/nginx/mediagoblin.example.access.log; + error_log /var/log/nginx/mediagoblin.example.error.log; + + # MediaGoblin's stock static files: CSS, JS, etc. + location /mgoblin_static/ { + alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/; + } + + # Instance specific media: + location /mgoblin_media/ { + alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; + } + + # Mounting MediaGoblin itself via FastCGI. + location / { + fastcgi_pass 127.0.0.1:26543; + include /etc/nginx/fastcgi_params; + + # our understanding vs nginx's handling of script_name vs + # path_info don't match :) + fastcgi_param PATH_INFO $fastcgi_script_name; + fastcgi_param SCRIPT_NAME ""; } + } Now, nginx instance is configured to serve the MediaGoblin application. Perform a quick test to ensure that this configuration works. Restart nginx so it picks up your changes, with a command that -resembles one of the following (as the root user:) :: +resembles one of the following (as the root user):: - sudo /etc/init.d/nginx restart - sudo /etc/rc.d/nginx restart + sudo /etc/init.d/nginx restart + sudo /etc/rc.d/nginx restart Now start MediaGoblin. Use the following command sequence as an -example: :: +example:: - cd /srv/mediagoblin.example.org/mediagoblin/ - ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 + cd /srv/mediagoblin.example.org/mediagoblin/ + ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 Visit the site you've set up in your browser by visiting . You should see MediaGoblin! diff --git a/docs/source/foreword.rst b/docs/source/foreword.rst index 835a7e7a..aa27647f 100644 --- a/docs/source/foreword.rst +++ b/docs/source/foreword.rst @@ -5,14 +5,14 @@ Foreword About the MediaGoblin Manual ============================ -This is the user manual for MediaGoblin. It covers how to set up and -configure MediaGoblin and the kind of information that someone running -MediaGoblin would need to know. +This is the site administrator manual for MediaGoblin. It covers how +to set up and configure MediaGoblin and the kind of information that +someone running MediaGoblin would need to know. We have other documentation at: * http://mediagoblin.org/join/ for general "join us" information -* http://wiki.mediagoblin.org/ for our contributor-focused wiki +* http://wiki.mediagoblin.org/ for our contributor/developer-focused wiki Improving the MediaGobiin Manual diff --git a/docs/source/production-deployments.rst b/docs/source/production-deployments.rst index 7bf26169..ef0bcad6 100644 --- a/docs/source/production-deployments.rst +++ b/docs/source/production-deployments.rst @@ -4,8 +4,7 @@ Considerations for Production Deployments This document contains a number of suggestions for deploying MediaGoblin in actual production environments. Consider -":doc:`deploying`" for a basic overview of how to deploy Media -Goblin. +":doc:`deploying`" for a basic overview of how to deploy MediaGoblin. Deploy with Paste ----------------- @@ -17,11 +16,11 @@ process. Use the following command as the basis for such a script: :: - CELERY_ALWAYS_EAGER=true \ - /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ - /srv/mediagoblin.example.org/mediagoblin/paste.ini \ - --pid-file=/var/run/mediagoblin.pid \ - --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ + CELERY_ALWAYS_EAGER=true \ + /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ + /srv/mediagoblin.example.org/mediagoblin/paste.ini \ + --pid-file=/var/run/mediagoblin.pid \ + --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 The above configuration places MediaGoblin in "always eager" mode with Celery, this means that submissions of content will be processed @@ -31,11 +30,11 @@ the user will be able to immediately return to the MediaGoblin site while processing is ongoing. In these cases, use the following command as the basis for your script: :: - CELERY_ALWAYS_EAGER=false \ - /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ - /srv/mediagoblin.example.org/mediagoblin/paste.ini \ - --pid-file=/var/run/mediagoblin.pid \ - --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 \ + CELERY_ALWAYS_EAGER=false \ + /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ + /srv/mediagoblin.example.org/mediagoblin/paste.ini \ + --pid-file=/var/run/mediagoblin.pid \ + --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 Separate Celery --------------- @@ -57,9 +56,9 @@ such as "ASCII art" or icon sharing, you will need to run ``celeryd`` as a separate process. Build an :ref:`init script ` around the following -command. +command:: - CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd + CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd Modify your existing MediaGoblin and application init scripts, if necessary, to prevent them from starting their own ``celeryd`` @@ -77,6 +76,6 @@ distribution/operating system. In the future, MediaGoblin will provide example scripts as examples. .. TODO insert init script here -.. TODO are additional concernts ? +.. TODO are additional concerns ? .. Other Concerns .. -------------- -- cgit v1.2.3 From 9bc2fc6c6a327a79ff5ad9d8f11f5b8f968154a6 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 12 Dec 2011 09:44:48 -0600 Subject: Added the "Media types" chapter --- docs/source/index.rst | 1 + docs/source/media-types.rst | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 docs/source/media-types.rst (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index 6ffe0974..f9c9285d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,6 +16,7 @@ Table of Contents: deploying production-deployments configuration + media-types help theming codebase diff --git a/docs/source/media-types.rst b/docs/source/media-types.rst new file mode 100644 index 00000000..809efe07 --- /dev/null +++ b/docs/source/media-types.rst @@ -0,0 +1,34 @@ +.. _media-types-chapter: + +==================== +Enabling Media Types +==================== + +In the future, there will be all sorts of media types you can enable, +but in the meanwhile there's only one additional media type: video. + +First, you should probably read ":doc:`configuration`" to make sure +you know how to modify the mediagoblin config file. + +Video +===== + +To enable video, first install gstreamer and the python-gstreamer +bindings (as well as whatever gstremaer extensions you want, +good/bad/ugly). On Debianoid systems: + + sudo apt-get install python-gst0.10 + +Next, modify (and possibly copy over from mediagoblin.ini) your +mediagoblin_local.ini. Uncomment this line in the [mediagoblin] +section: + + media_types = mediagoblin.media_types.image, mediagoblin.media_types.video + +Now you should be able to submit videos, and mediagoblin should +transcode them. + +Note that you almost certainly want to separate Celery from the normal +paste process or your users will probably find that their connections +time out as the video transcodes. To set that up, check out the +":doc:`production-deployments`" section of this manual. -- cgit v1.2.3 From e91a4dcb738f28fe75d0387175e97dc16ea977fb Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 12 Dec 2011 10:48:24 -0500 Subject: Tweak rest formatting --- docs/source/media-types.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/source') diff --git a/docs/source/media-types.rst b/docs/source/media-types.rst index 809efe07..76478143 100644 --- a/docs/source/media-types.rst +++ b/docs/source/media-types.rst @@ -15,13 +15,13 @@ Video To enable video, first install gstreamer and the python-gstreamer bindings (as well as whatever gstremaer extensions you want, -good/bad/ugly). On Debianoid systems: +good/bad/ugly). On Debianoid systems:: sudo apt-get install python-gst0.10 -Next, modify (and possibly copy over from mediagoblin.ini) your -mediagoblin_local.ini. Uncomment this line in the [mediagoblin] -section: +Next, modify (and possibly copy over from ``mediagoblin.ini``) your +``mediagoblin_local.ini``. Uncomment this line in the ``[mediagoblin]`` +section:: media_types = mediagoblin.media_types.image, mediagoblin.media_types.video -- cgit v1.2.3 From a46f645e7fc724547979ced22c8f9b7aa4ae0d51 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 12 Dec 2011 11:12:59 -0500 Subject: Fix doc footer This has the correct copyright statement. --- 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/conf.py | 7 +- docs/source/themes/mg/layout.html | 29 ++ docs/source/themes/mg/theme.conf | 5 + 6 files changed, 38 insertions(+), 372 deletions(-) delete mode 100644 docs/source/_templates/mg_theme/layout.html delete mode 100644 docs/source/_templates/mg_theme/static/default.css_t delete mode 100644 docs/source/_templates/mg_theme/theme.conf create mode 100644 docs/source/themes/mg/layout.html create mode 100644 docs/source/themes/mg/theme.conf (limited to 'docs/source') diff --git a/docs/source/_templates/mg_theme/layout.html b/docs/source/_templates/mg_theme/layout.html deleted file mode 100644 index eccda14b..00000000 --- a/docs/source/_templates/mg_theme/layout.html +++ /dev/null @@ -1,39 +0,0 @@ -{# - 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 deleted file mode 100644 index f200a0fe..00000000 --- a/docs/source/_templates/mg_theme/static/default.css_t +++ /dev/null @@ -1,299 +0,0 @@ -/* - * 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 deleted file mode 100644 index 49442e3b..00000000 --- a/docs/source/_templates/mg_theme/theme.conf +++ /dev/null @@ -1,31 +0,0 @@ -[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/conf.py b/docs/source/conf.py index eee9900f..f4d194e6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -28,7 +28,7 @@ sys.path.insert(0, os.path.abspath('.')) extensions = ["mgext.youcanhelp"] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ['source/_templates'] # The suffix of source filenames. source_suffix = '.rst' @@ -91,7 +91,8 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +# html_theme = 'default' +html_theme = 'mg' # 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 @@ -99,7 +100,7 @@ html_theme = 'default' #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +html_theme_path = ['themes'] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". diff --git a/docs/source/themes/mg/layout.html b/docs/source/themes/mg/layout.html new file mode 100644 index 00000000..891ed64c --- /dev/null +++ b/docs/source/themes/mg/layout.html @@ -0,0 +1,29 @@ +{# + 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 %} +
+
+ +MediaGoblin documentation released into the public domain via CC0. + + {%- 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 %} +
+
+{%- endblock %} diff --git a/docs/source/themes/mg/theme.conf b/docs/source/themes/mg/theme.conf new file mode 100644 index 00000000..f4fbd8cc --- /dev/null +++ b/docs/source/themes/mg/theme.conf @@ -0,0 +1,5 @@ +[theme] +inherit = default +stylesheet = default.css +pygments_style = sphinx + -- cgit v1.2.3 From 449f58e446ff50f9c84a99a123bd0225a4907f52 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 12 Dec 2011 11:41:29 -0500 Subject: Update version numbers --- docs/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index f4d194e6..829679b1 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.1.0' +version = '0.2.0' # The full version, including alpha/beta/rc tags. -release = '0.1.0' +release = '0.2.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From 6ae878e730e006ab674f12c581af8447a0994a9f Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 12 Dec 2011 11:52:24 -0500 Subject: Changer version to -dev --- docs/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 829679b1..dce254a1 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.2.0' +version = '0.3.0' # The full version, including alpha/beta/rc tags. -release = '0.2.0' +release = '0.3.0-dev' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From b957cba0cb9b6de33f9d50001a381ea94d9de57a Mon Sep 17 00:00:00 2001 From: Jef van Schendel Date: Fri, 6 Jan 2012 19:56:50 +0100 Subject: First push with new style (includes css file, logo image, fonts) --- docs/source/conf.py | 2 +- docs/source/themes/mg/static/fonts/Lato-Bold.ttf | Bin 0 -> 93224 bytes .../themes/mg/static/fonts/Lato-BoldItalic.ttf | Bin 0 -> 81936 bytes docs/source/themes/mg/static/fonts/Lato-Italic.ttf | Bin 0 -> 83680 bytes .../source/themes/mg/static/fonts/Lato-Regular.ttf | Bin 0 -> 96044 bytes docs/source/themes/mg/static/fonts/OFL_1.1.txt | 97 ++++++++++++++ docs/source/themes/mg/static/logo_docs.png | Bin 0 -> 6522 bytes docs/source/themes/mg/static/mg.css | 145 +++++++++++++++++++++ docs/source/themes/mg/theme.conf | 4 +- 9 files changed, 245 insertions(+), 3 deletions(-) create mode 100644 docs/source/themes/mg/static/fonts/Lato-Bold.ttf create mode 100644 docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf create mode 100644 docs/source/themes/mg/static/fonts/Lato-Italic.ttf create mode 100644 docs/source/themes/mg/static/fonts/Lato-Regular.ttf create mode 100644 docs/source/themes/mg/static/fonts/OFL_1.1.txt create mode 100644 docs/source/themes/mg/static/logo_docs.png create mode 100644 docs/source/themes/mg/static/mg.css (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index dce254a1..3014e592 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -111,7 +111,7 @@ html_theme_path = ['themes'] # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +html_logo = 'logo_docs.png' # 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 diff --git a/docs/source/themes/mg/static/fonts/Lato-Bold.ttf b/docs/source/themes/mg/static/fonts/Lato-Bold.ttf new file mode 100644 index 00000000..bc3529fc Binary files /dev/null and b/docs/source/themes/mg/static/fonts/Lato-Bold.ttf differ diff --git a/docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf b/docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf new file mode 100644 index 00000000..2cf5ae0d Binary files /dev/null and b/docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf differ diff --git a/docs/source/themes/mg/static/fonts/Lato-Italic.ttf b/docs/source/themes/mg/static/fonts/Lato-Italic.ttf new file mode 100644 index 00000000..11ca3eb6 Binary files /dev/null and b/docs/source/themes/mg/static/fonts/Lato-Italic.ttf differ diff --git a/docs/source/themes/mg/static/fonts/Lato-Regular.ttf b/docs/source/themes/mg/static/fonts/Lato-Regular.ttf new file mode 100644 index 00000000..26ce1002 Binary files /dev/null and b/docs/source/themes/mg/static/fonts/Lato-Regular.ttf differ diff --git a/docs/source/themes/mg/static/fonts/OFL_1.1.txt b/docs/source/themes/mg/static/fonts/OFL_1.1.txt new file mode 100644 index 00000000..f1a20ac1 --- /dev/null +++ b/docs/source/themes/mg/static/fonts/OFL_1.1.txt @@ -0,0 +1,97 @@ +Copyright (c) , (), +with Reserved Font Name . +Copyright (c) , (), +with Reserved Font Name . +Copyright (c) , (). + +This Font Software is licensed under the SIL Open Font License, Version 1.1. +This license is copied below, and is also available with a FAQ at: +http://scripts.sil.org/OFL + + +----------------------------------------------------------- +SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 +----------------------------------------------------------- + +PREAMBLE +The goals of the Open Font License (OFL) are to stimulate worldwide +development of collaborative font projects, to support the font creation +efforts of academic and linguistic communities, and to provide a free and +open framework in which fonts may be shared and improved in partnership +with others. + +The OFL allows the licensed fonts to be used, studied, modified and +redistributed freely as long as they are not sold by themselves. The +fonts, including any derivative works, can be bundled, embedded, +redistributed and/or sold with any software provided that any reserved +names are not used by derivative works. The fonts and derivatives, +however, cannot be released under any other type of license. The +requirement for fonts to remain under this license does not apply +to any document created using the fonts or their derivatives. + +DEFINITIONS +"Font Software" refers to the set of files released by the Copyright +Holder(s) under this license and clearly marked as such. This may +include source files, build scripts and documentation. + +"Reserved Font Name" refers to any names specified as such after the +copyright statement(s). + +"Original Version" refers to the collection of Font Software components as +distributed by the Copyright Holder(s). + +"Modified Version" refers to any derivative made by adding to, deleting, +or substituting -- in part or in whole -- any of the components of the +Original Version, by changing formats or by porting the Font Software to a +new environment. + +"Author" refers to any designer, engineer, programmer, technical +writer or other person who contributed to the Font Software. + +PERMISSION & CONDITIONS +Permission is hereby granted, free of charge, to any person obtaining +a copy of the Font Software, to use, study, copy, merge, embed, modify, +redistribute, and sell modified and unmodified copies of the Font +Software, subject to the following conditions: + +1) Neither the Font Software nor any of its individual components, +in Original or Modified Versions, may be sold by itself. + +2) Original or Modified Versions of the Font Software may be bundled, +redistributed and/or sold with any software, provided that each copy +contains the above copyright notice and this license. These can be +included either as stand-alone text files, human-readable headers or +in the appropriate machine-readable metadata fields within text or +binary files as long as those fields can be easily viewed by the user. + +3) No Modified Version of the Font Software may use the Reserved Font +Name(s) unless explicit written permission is granted by the corresponding +Copyright Holder. This restriction only applies to the primary font name as +presented to the users. + +4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font +Software shall not be used to promote, endorse or advertise any +Modified Version, except to acknowledge the contribution(s) of the +Copyright Holder(s) and the Author(s) or with their explicit written +permission. + +5) The Font Software, modified or unmodified, in part or in whole, +must be distributed entirely under this license, and must not be +distributed under any other license. The requirement for fonts to +remain under this license does not apply to any document created +using the Font Software. + +TERMINATION +This license becomes null and void if any of the above conditions are +not met. + +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE +COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL +DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM +OTHER DEALINGS IN THE FONT SOFTWARE. diff --git a/docs/source/themes/mg/static/logo_docs.png b/docs/source/themes/mg/static/logo_docs.png new file mode 100644 index 00000000..92879965 Binary files /dev/null and b/docs/source/themes/mg/static/logo_docs.png differ diff --git a/docs/source/themes/mg/static/mg.css b/docs/source/themes/mg/static/mg.css new file mode 100644 index 00000000..3a0a1336 --- /dev/null +++ b/docs/source/themes/mg/static/mg.css @@ -0,0 +1,145 @@ +@import url("basic.css"); + +/* text fonts and styles */ + +@font-face { + font-family: 'Lato'; + font-style: normal; + font-weight: 700; + src: local('Lato Bold'), local('Lato-Bold'), url('fonts/Lato-Bold.ttf') format('truetype'); +} +@font-face { + font-family: 'Lato'; + font-style: italic; + font-weight: 400; + src: local('Lato Italic'), local('Lato-Italic'), url('fonts/Lato-Italic.ttf') format('truetype'); +} +@font-face { + font-family: 'Lato'; + font-style: italic; + font-weight: 700; + src: local('Lato Bold Italic'), local('Lato-BoldItalic'), url('fonts/Lato-BoldItalic.ttf') format('truetype'); +} +@font-face { + font-family: 'Lato'; + font-style: normal; + font-weight: 400; + src: local('Lato Regular'), local('Lato-Regular'), url('fonts/Lato-Regular.ttf') format('truetype'); +} + +body { + font: 16px 'Lato',Helvetica,Arial,sans-serif; + background-color: #FCFCFC; + color: #3C3C3C; + margin: 0; + padding: 0; +} + +h1, h2, h3, h4, h5, h6 { + border-bottom: 1px solid #CCCCCC; + background: none; + color: black; + font-weight: bold; + padding-bottom: 0.17em; + padding-top: 0.5em; +} + +h1 { + font-size: 1.875em; +} + +h2 { + font-size: 1.375em; +} + +h3, h4, h5, h6 { + font-size: 1.125em; +} + +p { + font-weight: normal; + margin: 0.4em 0 0.5em; +} + +a { + color: #499776; +} + +a:visited { + color: #2A5744; +} + +a:active { + color: #65D1A3; +} + +h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { + text-decoration: none; +} + +div.topic, pre { + background-color: #F1F1F1; + border: 1px dashed #ccc; + color: black; + line-height: 1.1em; + padding: 1em; +} + +code, tt { + font: 14px monospace,"Courier New"; + background-color: #FFFFDD; + border: thin solid #bbb; + padding-left: 5px; + padding-right: 5px; +} + +pre { + font: 14px monospace,"Courier New"; +} + +div.related a, div.related a:visited, div.related a:active { + color: #86D4B1; +} + +/* layout */ + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 60px 0 0 230px; +} + +div.body { + padding: 0 20px 30px 20px; +} + +div.footer { + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 20px; +} + +div.sphinxsidebar ul { + margin: 10px 10px 10px 0; + padding: 0; +} + +div.related { + line-height: 30px; + font-size: 90%; + width: 100%; + background-color: #161616; + color: #C3C3C3; +} + +p.logo { + margin-bottom: 20px; +} diff --git a/docs/source/themes/mg/theme.conf b/docs/source/themes/mg/theme.conf index f4fbd8cc..dd58038a 100644 --- a/docs/source/themes/mg/theme.conf +++ b/docs/source/themes/mg/theme.conf @@ -1,5 +1,5 @@ [theme] -inherit = default -stylesheet = default.css +inherit = basic +stylesheet = mg.css pygments_style = sphinx -- cgit v1.2.3 From 242509239fddf9ebb904dc9c174da522f3bdc8b7 Mon Sep 17 00:00:00 2001 From: Jef van Schendel Date: Fri, 6 Jan 2012 23:58:43 +0100 Subject: New docs logo, small css changes --- docs/source/themes/mg/static/logo_docs.png | Bin 6522 -> 6626 bytes docs/source/themes/mg/static/mg.css | 6 +++--- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/themes/mg/static/logo_docs.png b/docs/source/themes/mg/static/logo_docs.png index 92879965..99f04cc7 100644 Binary files a/docs/source/themes/mg/static/logo_docs.png and b/docs/source/themes/mg/static/logo_docs.png differ diff --git a/docs/source/themes/mg/static/mg.css b/docs/source/themes/mg/static/mg.css index 3a0a1336..3fa842cd 100644 --- a/docs/source/themes/mg/static/mg.css +++ b/docs/source/themes/mg/static/mg.css @@ -109,7 +109,7 @@ div.documentwrapper { } div.bodywrapper { - margin: 60px 0 0 230px; + margin: 0 0 0 270px; } div.body { @@ -124,7 +124,7 @@ div.footer { } div.sphinxsidebarwrapper { - padding: 10px 5px 0 20px; + padding: 10px 5px 0 30px; } div.sphinxsidebar ul { @@ -141,5 +141,5 @@ div.related { } p.logo { - margin-bottom: 20px; + margin-top: 30px; } -- cgit v1.2.3 From 0788e48c0ec4b0f32867d32e31ab6b204ee0df8e Mon Sep 17 00:00:00 2001 From: Jef van Schendel Date: Sat, 7 Jan 2012 00:04:38 +0100 Subject: Increase docs sidebar width --- docs/source/themes/mg/static/mg.css | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/source') diff --git a/docs/source/themes/mg/static/mg.css b/docs/source/themes/mg/static/mg.css index 3fa842cd..b9355a5d 100644 --- a/docs/source/themes/mg/static/mg.css +++ b/docs/source/themes/mg/static/mg.css @@ -123,6 +123,10 @@ div.footer { font-size: 75%; } +div.sphinxsidebar { + width: 240px; +} + div.sphinxsidebarwrapper { padding: 10px 5px 0 30px; } -- cgit v1.2.3 From 20659de2344ccb8d14f8deaeaf9628d84a966e5a Mon Sep 17 00:00:00 2001 From: Jef van Schendel Date: Fri, 13 Jan 2012 17:38:20 +0100 Subject: Add CC0 license header to Sphinx MediaGoblin theme (mg.css) --- docs/source/themes/mg/static/mg.css | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/source') diff --git a/docs/source/themes/mg/static/mg.css b/docs/source/themes/mg/static/mg.css index b9355a5d..96344df4 100644 --- a/docs/source/themes/mg/static/mg.css +++ b/docs/source/themes/mg/static/mg.css @@ -1,3 +1,15 @@ +/* + +MediaGoblin theme - MediaGoblin-style Sphinx documentation theme + +Written in 2012 by Jef van Schendel + +To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty. + +You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see . + +*/ + @import url("basic.css"); /* text fonts and styles */ -- cgit v1.2.3 From 95ff15d66e89d4aacc9a452410efa0b8e9c602dd Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 2 Feb 2012 09:29:25 -0600 Subject: Updating deployment guide so that it can handle the current virtualenv site-packages changes Now it should try using --system-site-packages and if that fails (older version) it tries it without the argument. --- docs/source/deploying.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 4aded2e6..a8ee6ff1 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -118,7 +118,7 @@ Clone the MediaGoblin repository:: And setup the in-package virtualenv:: cd mediagoblin - virtualenv . && ./bin/python setup.py develop + (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop .. note:: -- cgit v1.2.3 From 473a4431c2632891e152913c7b4eed6fe7ba8bb3 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Tue, 7 Feb 2012 21:25:41 -0600 Subject: Added CC0 header to all MediaGoblin docs in docs/source/ --- docs/source/about.rst | 13 +++++++++++++ docs/source/codebase.rst | 13 +++++++++++++ docs/source/configuration.rst | 13 +++++++++++++ docs/source/deploying.rst | 13 +++++++++++++ docs/source/foreword.rst | 13 +++++++++++++ docs/source/help.rst | 13 +++++++++++++ docs/source/index.rst | 13 +++++++++++++ docs/source/media-types.rst | 13 +++++++++++++ docs/source/production-deployments.rst | 13 +++++++++++++ docs/source/theming.rst | 13 +++++++++++++ 10 files changed, 130 insertions(+) (limited to 'docs/source') diff --git a/docs/source/about.rst b/docs/source/about.rst index 1a2df809..7a6aa510 100644 --- a/docs/source/about.rst +++ b/docs/source/about.rst @@ -1,3 +1,16 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + ======================= About GNU MediaGoblin ======================= diff --git a/docs/source/codebase.rst b/docs/source/codebase.rst index 28d73802..2518e48f 100644 --- a/docs/source/codebase.rst +++ b/docs/source/codebase.rst @@ -1,3 +1,16 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + .. _codebase-chapter: ======================== diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 1e22ad2d..6596cef4 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -1,3 +1,16 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + .. _configuration-chapter: ======================== diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index a8ee6ff1..ce39dc4e 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -1,3 +1,16 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + ===================== Deploying MediaGoblin ===================== diff --git a/docs/source/foreword.rst b/docs/source/foreword.rst index aa27647f..be0c84b8 100644 --- a/docs/source/foreword.rst +++ b/docs/source/foreword.rst @@ -1,3 +1,16 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + ======== Foreword ======== diff --git a/docs/source/help.rst b/docs/source/help.rst index 34d4f37e..4b584ac1 100644 --- a/docs/source/help.rst +++ b/docs/source/help.rst @@ -1,3 +1,16 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + ================================== How to Get Help with MediaGoblin ================================== diff --git a/docs/source/index.rst b/docs/source/index.rst index f9c9285d..444ed688 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,3 +1,16 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + .. 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 diff --git a/docs/source/media-types.rst b/docs/source/media-types.rst index 76478143..86409b55 100644 --- a/docs/source/media-types.rst +++ b/docs/source/media-types.rst @@ -1,3 +1,16 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + .. _media-types-chapter: ==================== diff --git a/docs/source/production-deployments.rst b/docs/source/production-deployments.rst index ef0bcad6..1e6631db 100644 --- a/docs/source/production-deployments.rst +++ b/docs/source/production-deployments.rst @@ -1,3 +1,16 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + ========================================= Considerations for Production Deployments ========================================= diff --git a/docs/source/theming.rst b/docs/source/theming.rst index 2f4fcb4c..7584b688 100644 --- a/docs/source/theming.rst +++ b/docs/source/theming.rst @@ -1,3 +1,16 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + .. _theming-chapter: ===================== -- cgit v1.2.3 From 0c8e20cf13db50f2e51ade41e204ae5e0501e4e5 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 8 Feb 2012 11:07:19 -0500 Subject: Minor rewording Tried to address confusion I had when I read the document and tweaked some formatting. --- docs/source/configuration.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'docs/source') diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 6596cef4..a3dafa4c 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -20,6 +20,7 @@ Configuring MediaGoblin So! You've got MediaGoblin up and running, but you need to adjust some configuration parameters. Well you've come to the right place! + MediaGoblin's config files ========================== @@ -84,16 +85,20 @@ Common changes Enabling email notifications ---------------------------- -You'll almost certainly want to enable sending emails. By default, +You'll almost certainly want to enable sending email. By default, MediaGoblin doesn't really do this... for the sake of developer -convenience, it runs in "email debug mode". Change this:: +convenience, it runs in "email debug mode". + +To make MediaGoblin send email, you need a mailer daemon. + +Change this in your ``mediagoblin.ini`` file:: email_debug_mode = false -You can (and should) change the "from" email address by setting -``email_sender_address``. +You should also change the "from" email address by setting +``email_sender_address``. For example:: -Note that you need a mailer daemon running for this to work. + email_sender_address = "foo@example.com" If you have more custom SMTP settings, you also have the following options at your disposal, which are all optional, and do exactly what @@ -104,17 +109,19 @@ they sound like. - email_smtp_user - email_smtp_pass + All other configuration changes ------------------------------- To be perfectly honest, there are quite a few options and we haven't had -time to document them all +time to document them all. So here's a cop-out section saying that if you get into trouble, hop onto IRC and we'll help you out:: #mediagoblin on irc.freenode.net + Celery ====== -- cgit v1.2.3 From 973f37e9c39a8784f21f97a256890509eefb6f31 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 9 Feb 2012 09:10:08 -0600 Subject: Updating codebase.rst to reflect the modern mediagoblin world - adding/removing libraries listed as appropriate - buildout->virtualenv references - Updating directory structure description to reflect current reality --- docs/source/codebase.rst | 53 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 42 insertions(+), 11 deletions(-) (limited to 'docs/source') diff --git a/docs/source/codebase.rst b/docs/source/codebase.rst index 2518e48f..e784c9e5 100644 --- a/docs/source/codebase.rst +++ b/docs/source/codebase.rst @@ -48,8 +48,10 @@ Software Stack * `Nose `_: for unit tests - * `buildout `_: for getting dependencies, - building a runtime environment, ... + * `virtualenv `_: for setting up an + isolated environment to keep mediagoblin and related packages + (potentially not required if MediaGoblin is packaged for your + distro) * Data storage @@ -67,21 +69,47 @@ Software Stack * `Routes `_: for URL routing - * `Beaker `_: for handling sessions + * `Beaker `_: for handling sessions and + caching * `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 + * `MongoKit `_: the lightweight + ORM for MongoDB we're using which will make it easier to define + structures and all that (will be swapped out soon...) + + * `SQLAlchemy `_: SQL ORM and database + interaction library for Python. We'll be moving to this in the + upcoming move to SQL. + + * `Babel `_: Used to extract and compile + translations. + + * `Markdown (for python) `_: + implementation of `Markdown `_ + text-to-html tool to make it easy for people to write richtext + comments, descriptions, and etc. + + * `lxml `_: nice xml and html processing for + python. + +* Media processing libraries + + * `Python Imaging Library `_: + used to resize and otherwise convert images for display. + + * `GStreamer `_: (Optional, for + video hosting sites only) Used to transcode video, and in the + future, probably audio too. + + * `chardet `_: (Optional, for + ascii art hosting sites only) Used to make ascii art thumbnails. * Front end @@ -92,7 +120,8 @@ Software Stack What's where ============ -After you've run buildout, you're faced with the following directory +After you've run checked out mediagoblin and followed the virtualenv +instantiation instructions, you're faced with the following directory tree:: mediagoblin/ @@ -102,12 +131,14 @@ tree:: | |- auth/ | \- submit/ |- docs/ # documentation + |- devtools/ # some scripts for developer convenience | - | # the below directories are generated by buildout. + | # the below directories are installed into your virtualenv checkout | |- bin/ # scripts |- develop-eggs/ - |- eggs/ + |- lib/ # python libraries installed into your virtualenv + |- include/ |- mediagoblin.egg-info/ |- parts/ |- user_dev/ # sessions, etc -- cgit v1.2.3 From efd69313d0a1ab01d96795d4dd098d6c30844e50 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 9 Feb 2012 09:15:23 -0600 Subject: Added info on how to enable ascii art --- docs/source/media-types.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs/source') diff --git a/docs/source/media-types.rst b/docs/source/media-types.rst index 86409b55..ec068422 100644 --- a/docs/source/media-types.rst +++ b/docs/source/media-types.rst @@ -45,3 +45,22 @@ Note that you almost certainly want to separate Celery from the normal paste process or your users will probably find that their connections time out as the video transcodes. To set that up, check out the ":doc:`production-deployments`" section of this manual. + + +Ascii art +========= + +To enable ascii art support, first install the +`chardet `_ +library, which is necessary for creating thumbnails of ascii art:: + + ./bin/easy_install chardet + + +Next, modify (and possibly copy over from ``mediagoblin.ini``) your +``mediagoblin_local.ini``. Uncomment or add to the media_types line +'mediagoblin.media_types.ascii' like so:: + + media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii + +Now any .txt file you uploaded will be processed as ascii art! -- cgit v1.2.3 From 1da5052ff7b415efa6e523ed21a6a0a98c391432 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 9 Feb 2012 10:23:03 -0500 Subject: Removing youcanhelp stuff This was never used. It doesn't support Texinfo files. It was only half completed. Best to remove it. --- docs/source/conf.py | 2 +- docs/source/mgext/__init__.py | 0 docs/source/mgext/youcanhelp.py | 44 ----------------------------------------- 3 files changed, 1 insertion(+), 45 deletions(-) delete mode 100644 docs/source/mgext/__init__.py delete mode 100644 docs/source/mgext/youcanhelp.py (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 3014e592..16fd22a9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -25,7 +25,7 @@ sys.path.insert(0, os.path.abspath('.')) # 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"] +extensions = [] # Add any paths that contain templates here, relative to this directory. templates_path = ['source/_templates'] diff --git a/docs/source/mgext/__init__.py b/docs/source/mgext/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/source/mgext/youcanhelp.py b/docs/source/mgext/youcanhelp.py deleted file mode 100644 index a99d0e4d..00000000 --- a/docs/source/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) -- cgit v1.2.3 From 58301e093c7b99dc66b1e9255e34ef2e90e48d4d Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 9 Feb 2012 10:44:36 -0500 Subject: Update version numbers --- docs/source/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 16fd22a9..6b5dd93b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -41,16 +41,16 @@ master_doc = 'index' # General information about the project. project = u'GNU MediaGoblin' -copyright = u'2011, Free Software Foundation, Inc and contributors' +copyright = u'2011, 2012 GNU MediaGoblin 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.3.0' +version = '0.2.1' # The full version, including alpha/beta/rc tags. -release = '0.3.0-dev' +release = '0.2.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From 934d0b67a00f764fa2bc6ce44f31864f3804a44e Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 9 Feb 2012 10:49:50 -0500 Subject: Update version to 0.3.0-dev --- docs/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 6b5dd93b..8aedf596 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -48,9 +48,9 @@ copyright = u'2011, 2012 GNU MediaGoblin contributors' # built documents. # # The short X.Y version. -version = '0.2.1' +version = '0.3.0' # The full version, including alpha/beta/rc tags. -release = '0.2.1' +release = '0.3.0-dev" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From 6e03e586718ad06da38e3f82a043e35643bb9764 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 9 Feb 2012 11:00:30 -0500 Subject: Fix docs version --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 8aedf596..aafcf128 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -50,7 +50,7 @@ copyright = u'2011, 2012 GNU MediaGoblin contributors' # The short X.Y version. version = '0.3.0' # The full version, including alpha/beta/rc tags. -release = '0.3.0-dev" +release = '0.3.0-dev' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From 9dcd8436a9c97276e69b208c7c110d5875d1400d Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 18 Mar 2012 14:39:35 -0500 Subject: Fixing manual tyop: MediaGoblin, not MediaGobiin (thanks gandaro!) --- docs/source/foreword.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/foreword.rst b/docs/source/foreword.rst index be0c84b8..39ece25d 100644 --- a/docs/source/foreword.rst +++ b/docs/source/foreword.rst @@ -28,7 +28,7 @@ We have other documentation at: * http://wiki.mediagoblin.org/ for our contributor/developer-focused wiki -Improving the MediaGobiin Manual +Improving the MediaGoblin Manual ================================ There are a few ways---please pick whichever method is convenient for -- cgit v1.2.3 From 582958e333e9624654d57fb9e17d3340b5d0ac9b Mon Sep 17 00:00:00 2001 From: Elrond Date: Thu, 29 Mar 2012 13:15:38 +0200 Subject: The video media_type needs pygtk/gtk. Note in the docs, that the video media_type needs the gtk and pygtk modules and where to get them on debian. --- docs/source/media-types.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/source') diff --git a/docs/source/media-types.rst b/docs/source/media-types.rst index ec068422..a6e76385 100644 --- a/docs/source/media-types.rst +++ b/docs/source/media-types.rst @@ -32,6 +32,10 @@ good/bad/ugly). On Debianoid systems:: sudo apt-get install python-gst0.10 +Currently you need the gtk and pygtk modules:: + + sudo apt-get install python-gtk2 + Next, modify (and possibly copy over from ``mediagoblin.ini``) your ``mediagoblin_local.ini``. Uncomment this line in the ``[mediagoblin]`` section:: -- cgit v1.2.3 From c3c2f163c5c800d98a1db3d947479a6312d5a916 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Fri, 30 Mar 2012 00:18:54 +0200 Subject: Updated Video docs, so that I won't forget --- docs/source/media-types.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) (limited to 'docs/source') diff --git a/docs/source/media-types.rst b/docs/source/media-types.rst index a6e76385..647f2b42 100644 --- a/docs/source/media-types.rst +++ b/docs/source/media-types.rst @@ -30,11 +30,7 @@ To enable video, first install gstreamer and the python-gstreamer bindings (as well as whatever gstremaer extensions you want, good/bad/ugly). On Debianoid systems:: - sudo apt-get install python-gst0.10 - -Currently you need the gtk and pygtk modules:: - - sudo apt-get install python-gtk2 + sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} gstreamer0.10-ffmpeg Next, modify (and possibly copy over from ``mediagoblin.ini``) your ``mediagoblin_local.ini``. Uncomment this line in the ``[mediagoblin]`` -- cgit v1.2.3 From 775ec9e8f77cb4dd0d4a0388d40e0ae813bbf244 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Tue, 3 Apr 2012 00:49:24 +0200 Subject: Updated documentation Added PostgreSQL deployment documentation --- docs/source/deploying.rst | 91 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 88 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index ce39dc4e..53eb0adb 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -41,26 +41,88 @@ MediaGoblin has the following core dependencies: - Python 2.6 or 2.7 - `python-lxml `_ - `git `_ -- `MongoDB `_ +- `SQLite `_/`PostgreSQL `_ - `Python Imaging Library `_ (PIL) - `virtualenv `_ On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and derivatives) issue the following command: :: - sudo apt-get install mongodb git-core python python-dev python-lxml \ + sudo apt-get install git-core python python-dev python-lxml \ python-imaging python-virtualenv On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the following command: :: - yum install mongodb-server python-paste-deploy python-paste-script \ + yum install python-paste-deploy python-paste-script \ git-core python python-devel python-lxml python-imaging \ python-virtualenv +Configure PostgreSQL +~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + MediaGoblin currently supports PostgreSQL and SQLite. The default is a + local SQLite database. This will "just work" for small deployments. If + you don't want/need postgres, ignore all the postgres related parts. For + medium to large deployments we recommend PostgreSQL. + +These are the packages needed for Debian Wheezy (testing): :: + + sudo apt-get install postgresql postgresql-client + +The installation process will create a new *system* user named ``postgres``, +it will have privilegies sufficient to manage the database. We will create a +new database user with restricted privilegies and a new database owned by our +restricted database user for our MediaGoblin instance. + +In this example, the database user will be ``mediagoblin`` and the database +name will be ``mediagoblin`` too. + +To create our new user, run: :: + + sudo -u postgres createuser mediagoblin + +then answer NO to *all* the questions: :: + + Shall the new role be a superuser? (y/n) n + Shall the new role be allowed to create databases? (y/n) n + Shall the new role be allowed to create more new roles? (y/n) n + +then create the database all our MediaGoblin data should be stored in: :: + + sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin + +where the first ``mediagoblin`` is the database owner and the second +``mediagoblin`` is the database name. + +.. caution:: Where is the password? + + These steps enable you to authenticate to the database in a password-less + manner via local UNIX authentication provided you run the MediaGoblin + application as a user with the same name as the user you created in + PostgreSQL. + + More on this in :ref:`Drop Privileges for MediaGoblin `. + + Configure MongoDB ~~~~~~~~~~~~~~~~~ +.. warning:: + + If this is a fresh setup and you have already set up PostgreSQL, you + will not need this step. + +First, install MongoDB. On a DEB-based system run: :: + + sudo apt-get install mongodb + +on a RPM-based system, run: :: + + yum install mongodb-server + After installing MongoDB some preliminary database configuration may be necessary. @@ -85,6 +147,8 @@ running a smaller instance, consider the `scaling down guide `_ for some appropriate tradeoffs to conserve space. +.. _drop-privileges-for-mediagoblin: + Drop Privileges for MediaGoblin ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -161,6 +225,27 @@ codebase, you should also run:: Deploy MediaGoblin Services --------------------------- +Configure MediaGoblin to use the PostgreSQL database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Edit the ``[mediagoblin]`` section in your ``mediagoblin_local.ini`` and +put in: :: + + sql_engine = postgresql:///mediagoblin + +if you are running the MediaGoblin application as the same 'user' as the +database owner. + +Update database data structures +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before you start using the database, you need to run: :: + + ./bin/gmg dbupdate + +to populate the database with the MediaGoblin data structures. + + Test the Server ~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 5be6425c2812945b1346f59c9b8188cdaf9168d9 Mon Sep 17 00:00:00 2001 From: Elrond Date: Thu, 5 Apr 2012 19:46:24 +0200 Subject: Start adding release notes. This is especially for noting the switch to sql and explaining how to convert your mongodb data over to sql. --- docs/source/index.rst | 1 + docs/source/relnotes.rst | 52 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) create mode 100644 docs/source/relnotes.rst (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index 444ed688..187a0382 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -31,6 +31,7 @@ Table of Contents: configuration media-types help + relnotes theming codebase diff --git a/docs/source/relnotes.rst b/docs/source/relnotes.rst new file mode 100644 index 00000000..7a157a0c --- /dev/null +++ b/docs/source/relnotes.rst @@ -0,0 +1,52 @@ +.. MediaGoblin Documentation + + Written in 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +============= +Release Notes +============= + +This chapter has important information for releases in it. +If you're upgrading from a previous release, please read it +carefully, or at least skim over it. + + +0.3.0 +===== + +This release has one important change. You need to act when +upgrading from a previous version! + +This release changes the database system from MongoDB to +SQL(alchemy). If you want to setup a fresh instance, just +follow the instructions in the deployment chapter. If on +the other hand you want to continue to use one instance, +read on. + +To convert our data from MongoDB to SQL(alchemy), you need +to follow these steps: + +1. Make sure your MongoDB is still running and has your + data, it's needed for the conversion. + +2. Configure the sql_engine URI in the config to represent + your target database (see: Deployment docs) + +3. You need an empty database. + +4. Then run the following command:: + + bin/gmg [-cf mediagoblin_config.ini] convert_mongo_to_sql + +5. Start your server and investigate. + +6. That's it. -- cgit v1.2.3 From abe74178270cf84c26ebda5e2209902b9f963fd5 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sat, 7 Apr 2012 12:26:40 -0400 Subject: Fix relnotes formatting * adds link to deployment docs. * tweaks formatting --- docs/source/deploying.rst | 2 ++ docs/source/relnotes.rst | 10 +++++----- 2 files changed, 7 insertions(+), 5 deletions(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 53eb0adb..ef1de621 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -11,6 +11,8 @@ Dedication along with this software. If not, see . +.. _deploying-chapter: + ===================== Deploying MediaGoblin ===================== diff --git a/docs/source/relnotes.rst b/docs/source/relnotes.rst index 7a157a0c..87b5e755 100644 --- a/docs/source/relnotes.rst +++ b/docs/source/relnotes.rst @@ -20,8 +20,8 @@ If you're upgrading from a previous release, please read it carefully, or at least skim over it. -0.3.0 -===== +0.3.0 (not yet released) +======================== This release has one important change. You need to act when upgrading from a previous version! @@ -38,14 +38,14 @@ to follow these steps: 1. Make sure your MongoDB is still running and has your data, it's needed for the conversion. -2. Configure the sql_engine URI in the config to represent - your target database (see: Deployment docs) +2. Configure the ``sql_engine`` URI in the config to represent + your target database (see: :ref:`deploying-chapter`) 3. You need an empty database. 4. Then run the following command:: - bin/gmg [-cf mediagoblin_config.ini] convert_mongo_to_sql + bin/gmg [-cf mediagoblin_config.ini] convert_mongo_to_sql 5. Start your server and investigate. -- cgit v1.2.3 From 7798f911ab31622efd6517585057c657454cebb0 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Fri, 20 Apr 2012 22:10:21 -0400 Subject: Documentation updates and fixes * Nixed some of the mongodb references--pretty sure we're done with that. * Fixed some awkward language. * Fixed : :: stuff. Sphinx lets you do :: so you don't need the additional colon. * Turned a paragraph into a .. note:: section. That makes it easier to notice and read. --- docs/source/codebase.rst | 9 +++------ docs/source/deploying.rst | 41 ++++++++++++++++++++++------------------- docs/source/media-types.rst | 30 ++++++++++++++++++++---------- 3 files changed, 45 insertions(+), 35 deletions(-) (limited to 'docs/source') diff --git a/docs/source/codebase.rst b/docs/source/codebase.rst index e784c9e5..6de71f07 100644 --- a/docs/source/codebase.rst +++ b/docs/source/codebase.rst @@ -55,8 +55,9 @@ Software Stack * Data storage - * `MongoDB `_: the document database backend - for storage + * `SQLAlchemy `_: SQL ORM and database + interaction library for Python. Currently we support sqlite and + postgress as backends. * Web application @@ -84,10 +85,6 @@ Software Stack ORM for MongoDB we're using which will make it easier to define structures and all that (will be swapped out soon...) - * `SQLAlchemy `_: SQL ORM and database - interaction library for Python. We'll be moving to this in the - upcoming move to SQL. - * `Babel `_: Used to extract and compile translations. diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index ef1de621..ed74b441 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -48,13 +48,13 @@ MediaGoblin has the following core dependencies: - `virtualenv `_ On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and -derivatives) issue the following command: :: +derivatives) issue the following command:: sudo apt-get install git-core python python-dev python-lxml \ python-imaging python-virtualenv On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the -following command: :: +following command:: yum install python-paste-deploy python-paste-script \ git-core python python-devel python-lxml python-imaging \ @@ -65,12 +65,14 @@ Configure PostgreSQL .. note:: - MediaGoblin currently supports PostgreSQL and SQLite. The default is a - local SQLite database. This will "just work" for small deployments. If - you don't want/need postgres, ignore all the postgres related parts. For - medium to large deployments we recommend PostgreSQL. + MediaGoblin currently supports PostgreSQL and SQLite. The default is a + local SQLite database. This will "just work" for small deployments. -These are the packages needed for Debian Wheezy (testing): :: + For medium to large deployments we recommend PostgreSQL. + + If you don't want/need postgres, skip this section. + +These are the packages needed for Debian Wheezy (testing):: sudo apt-get install postgresql postgresql-client @@ -82,17 +84,17 @@ restricted database user for our MediaGoblin instance. In this example, the database user will be ``mediagoblin`` and the database name will be ``mediagoblin`` too. -To create our new user, run: :: +To create our new user, run:: sudo -u postgres createuser mediagoblin -then answer NO to *all* the questions: :: +then answer NO to *all* the questions:: Shall the new role be a superuser? (y/n) n Shall the new role be allowed to create databases? (y/n) n Shall the new role be allowed to create more new roles? (y/n) n -then create the database all our MediaGoblin data should be stored in: :: +then create the database all our MediaGoblin data should be stored in:: sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin @@ -117,11 +119,11 @@ Configure MongoDB If this is a fresh setup and you have already set up PostgreSQL, you will not need this step. -First, install MongoDB. On a DEB-based system run: :: +First, install MongoDB. On a DEB-based system run:: sudo apt-get install mongodb -on a RPM-based system, run: :: +on a RPM-based system, run:: yum install mongodb-server @@ -167,7 +169,7 @@ assumes your local git repository will be located at Substitute your prefer ed local deployment path as needed. This document assumes that all operations are performed as this -user. To drop privileges to this user, run the following command: :: +user. To drop privileges to this user, run the following command:: su - [mediagoblin] @@ -179,7 +181,7 @@ Install MediaGoblin and Virtualenv .. note:: - As of |version|, MediaGoblin has a rapid development pace. As a result + MediaGoblin is still developing rapidly. As a result the following instructions recommend installing from the ``master`` branch of the git repository. Eventually production deployments will want to transition to running from more consistent releases. @@ -194,7 +196,7 @@ Clone the MediaGoblin repository:: git clone git://gitorious.org/mediagoblin/mediagoblin.git -And setup the in-package virtualenv:: +And set up the in-package virtualenv:: cd mediagoblin (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop @@ -219,7 +221,7 @@ flup:: ./bin/easy_install flup This concludes the initial configuration of the development -environment. In the future, if at any point you want update your +environment. In the future, you want update your codebase, you should also run:: ./bin/python setup.py develop --upgrade && ./bin/gmg migrate. @@ -230,18 +232,19 @@ Deploy MediaGoblin Services Configure MediaGoblin to use the PostgreSQL database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Edit the ``[mediagoblin]`` section in your ``mediagoblin_local.ini`` and -put in: :: +If you are using postgres, edit the ``[mediagoblin]`` section in your +``mediagoblin_local.ini`` and put in:: sql_engine = postgresql:///mediagoblin if you are running the MediaGoblin application as the same 'user' as the database owner. + Update database data structures ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Before you start using the database, you need to run: :: +Before you start using the database, you need to run:: ./bin/gmg dbupdate diff --git a/docs/source/media-types.rst b/docs/source/media-types.rst index 647f2b42..1cf7f30c 100644 --- a/docs/source/media-types.rst +++ b/docs/source/media-types.rst @@ -18,7 +18,8 @@ Enabling Media Types ==================== In the future, there will be all sorts of media types you can enable, -but in the meanwhile there's only one additional media type: video. +but in the meanwhile there are two additional media type: video and +ascii art. First, you should probably read ":doc:`configuration`" to make sure you know how to modify the mediagoblin config file. @@ -30,21 +31,27 @@ To enable video, first install gstreamer and the python-gstreamer bindings (as well as whatever gstremaer extensions you want, good/bad/ugly). On Debianoid systems:: - sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} gstreamer0.10-ffmpeg + sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \ + gstreamer0.10-ffmpeg Next, modify (and possibly copy over from ``mediagoblin.ini``) your -``mediagoblin_local.ini``. Uncomment this line in the ``[mediagoblin]`` -section:: +``mediagoblin_local.ini``. In the ``[mediagoblin]`` section, add +``mediagoblin.media_types.video`` to the ``media_types`` list. + +For example, if your system supported image and video media types, then +the list would look like this:: media_types = mediagoblin.media_types.image, mediagoblin.media_types.video Now you should be able to submit videos, and mediagoblin should transcode them. -Note that you almost certainly want to separate Celery from the normal -paste process or your users will probably find that their connections -time out as the video transcodes. To set that up, check out the -":doc:`production-deployments`" section of this manual. +.. note:: + + You almost certainly want to separate Celery from the normal + paste process or your users will probably find that their connections + time out as the video transcodes. To set that up, check out the + ":doc:`production-deployments`" section of this manual. Ascii art @@ -58,8 +65,11 @@ library, which is necessary for creating thumbnails of ascii art:: Next, modify (and possibly copy over from ``mediagoblin.ini``) your -``mediagoblin_local.ini``. Uncomment or add to the media_types line -'mediagoblin.media_types.ascii' like so:: +``mediagoblin_local.ini``. In the ``[mediagoblin]`` section, add +``mediagoblin.media_types.ascii`` to the ``media_types`` list. + +For example, if your system supported image and ascii art media types, then +the list would look like this:: media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii -- cgit v1.2.3 From fe191ea48a1e7b9b3eb28f3e58de93f77e372c87 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 29 Apr 2012 13:11:31 -0500 Subject: Removing references to MongoDB in docs/ --- docs/source/codebase.rst | 6 +----- docs/source/deploying.rst | 40 ---------------------------------------- 2 files changed, 1 insertion(+), 45 deletions(-) (limited to 'docs/source') diff --git a/docs/source/codebase.rst b/docs/source/codebase.rst index 6de71f07..3ef91290 100644 --- a/docs/source/codebase.rst +++ b/docs/source/codebase.rst @@ -81,10 +81,6 @@ Software Stack * `Celery `_: for task queuing (resizing images, encoding video, ...) - * `MongoKit `_: the lightweight - ORM for MongoDB we're using which will make it easier to define - structures and all that (will be swapped out soon...) - * `Babel `_: Used to extract and compile translations. @@ -148,7 +144,7 @@ Here are some interesting files and what they do: :routing.py: maps url paths to views :views.py: views handle http requests -:models.py: holds the mongodb schemas---these are the data structures +:models.py: holds the sqlalchemy schemas---these are the data structures we're working with You'll notice that there are several sub-directories: tests, diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index ed74b441..bd874150 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -111,46 +111,6 @@ where the first ``mediagoblin`` is the database owner and the second More on this in :ref:`Drop Privileges for MediaGoblin `. -Configure MongoDB -~~~~~~~~~~~~~~~~~ - -.. warning:: - - If this is a fresh setup and you have already set up PostgreSQL, you - will not need this step. - -First, install MongoDB. On a DEB-based system run:: - - sudo apt-get install mongodb - -on a RPM-based system, run:: - - yum install mongodb-server - -After installing MongoDB some preliminary database configuration may -be necessary. - -Ensure that MongoDB `journaling -`_ is enabled. Journaling -is enabled by default in version 2.0 and later 64-bit MongoDB instances. -Check your deployment, and consider enabling journaling if you're running -32-bit systems or earlier version. - -.. warning:: - - Running MongoDB without journaling risks general data corruption - and raises the possibility of losing data within a 60-second - window when the server restarts. - - MediaGoblin recommends enabling MongoDB's journaling feature by - adding a ``--journal`` flag to the command line or a "``journal: - true``" option to the configuration file. - -MongoDB can take a lot of space by default. If you're planning on -running a smaller instance, consider the `scaling down guide -`_ for some appropriate -tradeoffs to conserve space. - .. _drop-privileges-for-mediagoblin: Drop Privileges for MediaGoblin -- cgit v1.2.3 From 084a619079e9428efcedbf301412d539017a0ab4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 30 Apr 2012 22:05:27 -0500 Subject: ./bin/gmg migrate -> ./bin/gmg dbupdate in the docs --- docs/source/deploying.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index bd874150..fc0e2721 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -184,7 +184,7 @@ This concludes the initial configuration of the development environment. In the future, you want update your codebase, you should also run:: - ./bin/python setup.py develop --upgrade && ./bin/gmg migrate. + ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate Deploy MediaGoblin Services --------------------------- -- cgit v1.2.3 From 21a84362eab488533c259413d351550da3d12b2c Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 30 Apr 2012 22:12:07 -0500 Subject: Also tell people to install python-psycopg2 if using postgres in docs --- docs/source/deploying.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index fc0e2721..4d20da45 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -74,7 +74,7 @@ Configure PostgreSQL These are the packages needed for Debian Wheezy (testing):: - sudo apt-get install postgresql postgresql-client + sudo apt-get install postgresql postgresql-client python-psycopg2 The installation process will create a new *system* user named ``postgres``, it will have privilegies sufficient to manage the database. We will create a -- cgit v1.2.3 From 6e930791e9f998c83f6c58cd59939cf1d6da9379 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Tue, 1 May 2012 11:10:39 -0500 Subject: 0.3.0 *is* released! Reflect that in the release notes :) --- docs/source/relnotes.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/relnotes.rst b/docs/source/relnotes.rst index 87b5e755..93d2eb85 100644 --- a/docs/source/relnotes.rst +++ b/docs/source/relnotes.rst @@ -20,8 +20,8 @@ If you're upgrading from a previous release, please read it carefully, or at least skim over it. -0.3.0 (not yet released) -======================== +0.3.0 +===== This release has one important change. You need to act when upgrading from a previous version! -- cgit v1.2.3 From dce379221896bc5f3c0f4cabc99aea89ed75be2f Mon Sep 17 00:00:00 2001 From: greg Date: Tue, 1 May 2012 09:32:59 -0700 Subject: One character chage: "our" to "your" in the release notes as it makes more sense, I believe. --- docs/source/relnotes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/relnotes.rst b/docs/source/relnotes.rst index 93d2eb85..2efded73 100644 --- a/docs/source/relnotes.rst +++ b/docs/source/relnotes.rst @@ -32,7 +32,7 @@ follow the instructions in the deployment chapter. If on the other hand you want to continue to use one instance, read on. -To convert our data from MongoDB to SQL(alchemy), you need +To convert your data from MongoDB to SQL(alchemy), you need to follow these steps: 1. Make sure your MongoDB is still running and has your -- cgit v1.2.3 From 44f3d3b19a8f3a477156c655666626eb33b169b4 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 30 Apr 2012 09:48:00 -0700 Subject: Update version to 0.3.0 for release --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index aafcf128..07f546e0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -50,7 +50,7 @@ copyright = u'2011, 2012 GNU MediaGoblin contributors' # The short X.Y version. version = '0.3.0' # The full version, including alpha/beta/rc tags. -release = '0.3.0-dev' +release = '0.3.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From a736a5d5822106b5ac8aa1802fd2a97731e4168f Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 30 Apr 2012 11:03:35 -0700 Subject: Update version to 0.3.1.dev --- docs/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 07f546e0..41cf2529 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -48,9 +48,9 @@ copyright = u'2011, 2012 GNU MediaGoblin contributors' # built documents. # # The short X.Y version. -version = '0.3.0' +version = '0.3.1' # The full version, including alpha/beta/rc tags. -release = '0.3.0' +release = '0.3.1.dev' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From 518c5eb38bd1f00bbaf960e5606e31d42ddce29e Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sat, 5 May 2012 12:16:13 -0500 Subject: A couple of typos in docs... MedaGobilin->MediaGoblin --- docs/source/about.rst | 2 +- docs/source/deploying.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/about.rst b/docs/source/about.rst index 7a6aa510..1a831103 100644 --- a/docs/source/about.rst +++ b/docs/source/about.rst @@ -89,7 +89,7 @@ GNU MediaGoblin software is released under an AGPLv3 license. See the ``COPYING`` file in the root of the source for details. -Is MedaGobilin an official GNU project? What does that mean? +Is MedaGoblin an official GNU project? What does that mean? ============================================================= MediaGoblin is an official GNU project! This status means that we the diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst index 4d20da45..788b06d7 100644 --- a/docs/source/deploying.rst +++ b/docs/source/deploying.rst @@ -310,7 +310,7 @@ example:: ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 Visit the site you've set up in your browser by visiting -. You should see MediaGoblin! +. You should see MediaGoblin! .. note:: -- cgit v1.2.3 From c3dc1fb44036ad9f31d3da69919f3979d3025be6 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 6 May 2012 15:27:19 -0500 Subject: Apparently I can't correct typos right. MedaGoblin->MediaGoblin in docs --- docs/source/about.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/about.rst b/docs/source/about.rst index 1a831103..a6649129 100644 --- a/docs/source/about.rst +++ b/docs/source/about.rst @@ -89,7 +89,7 @@ GNU MediaGoblin software is released under an AGPLv3 license. See the ``COPYING`` file in the root of the source for details. -Is MedaGoblin an official GNU project? What does that mean? +Is MediaGoblin an official GNU project? What does that mean? ============================================================= MediaGoblin is an official GNU project! This status means that we the -- cgit v1.2.3 From 61d0af21309feb201fac3eec97961cc61cafd494 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 6 May 2012 15:28:13 -0500 Subject: gandaro points out we should have all headers end with question marks for consistency Done for about.rst --- docs/source/about.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/source') diff --git a/docs/source/about.rst b/docs/source/about.rst index a6649129..95647abb 100644 --- a/docs/source/about.rst +++ b/docs/source/about.rst @@ -19,8 +19,8 @@ :local: -What is GNU MediaGoblin -======================= +What is GNU MediaGoblin? +======================== In 2008, a number of free software developers and activists gathered at the FSF to attempt to answer the question "What should software @@ -43,8 +43,8 @@ support other media, like video, and provide tools to facilitate collaboration on media projects. -Why Build GNU MediaGoblin -========================= +Why Build GNU MediaGoblin? +========================== The Internet is designed---and works best---as a complex and endlessly resilient network. When key services and media outlets are @@ -62,8 +62,8 @@ make these kinds of services possible. We hope you'll join us, both as users and as contributors. -Who Contributes to the Project -============================== +Who Contributes to the Project? +=============================== You do! -- cgit v1.2.3 From 29b6f91740e68d804612ff68295020f6cfa16071 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 12 Mar 2012 21:17:08 -0400 Subject: 401. Plugin infrastructure * implements installing, loading and setup for plugins * codifies configuration * has a sample plugin * docs * tests --- docs/source/plugins.rst | 105 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 docs/source/plugins.rst (limited to 'docs/source') diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst new file mode 100644 index 00000000..3e036fdb --- /dev/null +++ b/docs/source/plugins.rst @@ -0,0 +1,105 @@ +========= + Plugins +========= + +GNU MediaGoblin supports plugins that, when installed, allow you to +augment MediaGoblin's behavior. + +This chapter covers discovering, installing, configuring and removing +plugins. + + +Discovering plugins +=================== + +MediaGoblin comes with core plugins. Core plugins are located in the +``mediagoblin.plugins`` module of the MediaGoblin code. Because they +come with MediaGoblin, you don't have to install them, but you do have +to add them to your config file if you're interested in using them. + +You can also write your own plugins and additionally find plugins +elsewhere on the Internet. Since these plugins don't come with +MediaGoblin, you must first install them, then add them to your +configuration. + + +Installing plugins +================== + +MediaGoblin core plugins don't need to be installed. For core plugins, +you can skip installation! + +If the plugin is not a core plugin and is packaged and available on +the Python Package Index, then you can install the plugin with pip:: + + pip install + +For example, if we wanted to install the plugin named +"mediagoblin-restrictfive", we would do:: + + pip install mediagoblin-restrictfive + +.. Note:: + + If you're using a virtual environment, make sure to activate the + virtual environment before installing with pip. Otherwise the + plugin may get installed in a different environment. + +Once you've installed the plugin software, you need to tell +MediaGoblin that this is a plugin you want MediaGoblin to use. To do +that, you edit the ``mediagoblin.ini`` file and add the plugin as a +subsection of the plugin section. + +For example, say the "mediagoblin-restrictfive" plugin had the Python +package path ``restrictfive``, then you would add ``restrictfive`` to +the ``plugins`` section as a subsection:: + + [plugins] + + [[restrictfive]] + + +Configuring plugins +=================== + +Generally, configuration goes in the ``.ini`` file. Configuration for +a specific plugin, goes in a subsection of the ``plugins`` section. + +Example 1: Core MediaGoblin plugin + +If you wanted to use the core MediaGoblin flatpages plugin, the module +for that is ``mediagoblin.plugins.flatpages`` and you would add that +to your ``.ini`` file like this:: + + [plugins] + + [[mediagoblin.plugins.flatpages]] + # configuration for flatpages plugin here! + +Example 2: Plugin that is not a core MediaGoblin plugin + +If you installed a hypothetical restrictfive plugin which is in the +module ``restrictfive``, your ``.ini`` file might look like this (with +comments making the bits clearer):: + + [plugins] + + [[restrictfive]] + # configuration for restrictfive here! + +Check the plugin's documentation for what configuration options are +available. + + +Removing plugins +================ + +To remove a plugin, use ``pip uninstall``. For example:: + + pip uninstall mediagoblin-restrictfive + +.. Note:: + + If you're using a virtual environment, make sure to activate the + virtual environment before uninstalling with pip. Otherwise the + plugin may get installed in a different environment. -- cgit v1.2.3 From 355fd6770dce14cf45fd696cda542cb190bb42cb Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 16 May 2012 21:04:52 -0400 Subject: Update documentation for plugins --- docs/source/plugins.rst | 56 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 12 deletions(-) (limited to 'docs/source') diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 3e036fdb..dfb69075 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -2,8 +2,8 @@ Plugins ========= -GNU MediaGoblin supports plugins that, when installed, allow you to -augment MediaGoblin's behavior. +GNU MediaGoblin supports plugins that allow you to augment MediaGoblin's +behavior. This chapter covers discovering, installing, configuring and removing plugins. @@ -18,19 +18,28 @@ come with MediaGoblin, you don't have to install them, but you do have to add them to your config file if you're interested in using them. You can also write your own plugins and additionally find plugins -elsewhere on the Internet. Since these plugins don't come with -MediaGoblin, you must first install them, then add them to your -configuration. +elsewhere on the Internet. Once you find a plugin you like, you need +to first install it, then add it to your configuration. + +.. todo:: how do you find plugins on the internet? Installing plugins ================== -MediaGoblin core plugins don't need to be installed. For core plugins, -you can skip installation! +Core plugins +------------ + +MediaGoblin core plugins don't need to be installed because they come +with MediaGoblin. Further, when you upgrade MediaGoblin, you will also +get updates to the core plugins. + + +Other plugins +------------- -If the plugin is not a core plugin and is packaged and available on -the Python Package Index, then you can install the plugin with pip:: +If the plugin is available on the `Python Package Index +`_, then you can install the plugin with pip:: pip install @@ -43,7 +52,8 @@ For example, if we wanted to install the plugin named If you're using a virtual environment, make sure to activate the virtual environment before installing with pip. Otherwise the - plugin may get installed in a different environment. + plugin may get installed in a different environment than the one + MediaGoblin is installed in. Once you've installed the plugin software, you need to tell MediaGoblin that this is a plugin you want MediaGoblin to use. To do @@ -62,8 +72,9 @@ the ``plugins`` section as a subsection:: Configuring plugins =================== -Generally, configuration goes in the ``.ini`` file. Configuration for -a specific plugin, goes in a subsection of the ``plugins`` section. +Configuration for a plugin goes in the subsection for that plugin. Core +plugins are documented in the administration guide. Other plugins +should come with documentation that tells you how to configure them. Example 1: Core MediaGoblin plugin @@ -75,6 +86,7 @@ to your ``.ini`` file like this:: [[mediagoblin.plugins.flatpages]] # configuration for flatpages plugin here! + directory = /srv/mediagoblin/flatpages Example 2: Plugin that is not a core MediaGoblin plugin @@ -103,3 +115,23 @@ To remove a plugin, use ``pip uninstall``. For example:: If you're using a virtual environment, make sure to activate the virtual environment before uninstalling with pip. Otherwise the plugin may get installed in a different environment. + + +Upgrading plugins +================= + +Core plugins +------------ + +Core plugins get upgraded automatically when you upgrade MediaGoblin +because they come with MediaGoblin. + + +Other plugins +------------- + +For plugins that you install with pip, you can upgrade them with pip:: + + pip install -U + +The ``-U`` tells pip to upgrade the package. -- cgit v1.2.3 From 2530ef7a1f682dcd5c4386d6b66b1fb71e8cc554 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 23 May 2012 20:21:03 -0400 Subject: Split docs into siteadmin and pluginwriter guides * create initial bits for plugin writer's guide * move siteadmin stuff to site administrator's guide * rework index.rst to support multiple guides * tweak some text * move files into subdirectories I verified that this still works with html and texinfo build targets. There's still a lot of work to do, but this is a good start. --- docs/source/_static/goblin.png | Bin 0 -> 47763 bytes docs/source/_static/snugglygoblin.png | Bin 0 -> 163754 bytes docs/source/about.rst | 101 ------- docs/source/codebase.rst | 160 ------------ docs/source/configuration.rst | 129 --------- docs/source/deploying.rst | 320 ----------------------- docs/source/foreword.rst | 48 ---- docs/source/goblin.png | Bin 47763 -> 0 bytes docs/source/help.rst | 29 -- docs/source/index.rst | 47 ++-- docs/source/media-types.rst | 76 ------ docs/source/plugins.rst | 137 ---------- docs/source/pluginwriter/foreward.rst | 43 +++ docs/source/production-deployments.rst | 94 ------- docs/source/relnotes.rst | 52 ---- docs/source/siteadmin/about.rst | 101 +++++++ docs/source/siteadmin/codebase.rst | 160 ++++++++++++ docs/source/siteadmin/configuration.rst | 129 +++++++++ docs/source/siteadmin/deploying.rst | 320 +++++++++++++++++++++++ docs/source/siteadmin/foreword.rst | 48 ++++ docs/source/siteadmin/help.rst | 29 ++ docs/source/siteadmin/media-types.rst | 76 ++++++ docs/source/siteadmin/plugins.rst | 137 ++++++++++ docs/source/siteadmin/production-deployments.rst | 94 +++++++ docs/source/siteadmin/relnotes.rst | 52 ++++ docs/source/siteadmin/theming.rst | 21 ++ docs/source/snugglygoblin.png | Bin 163754 -> 0 bytes docs/source/theming.rst | 21 -- 28 files changed, 1240 insertions(+), 1184 deletions(-) create mode 100644 docs/source/_static/goblin.png create mode 100644 docs/source/_static/snugglygoblin.png delete mode 100644 docs/source/about.rst delete mode 100644 docs/source/codebase.rst delete mode 100644 docs/source/configuration.rst delete mode 100644 docs/source/deploying.rst delete mode 100644 docs/source/foreword.rst delete mode 100644 docs/source/goblin.png delete mode 100644 docs/source/help.rst delete mode 100644 docs/source/media-types.rst delete mode 100644 docs/source/plugins.rst create mode 100644 docs/source/pluginwriter/foreward.rst delete mode 100644 docs/source/production-deployments.rst delete mode 100644 docs/source/relnotes.rst create mode 100644 docs/source/siteadmin/about.rst create mode 100644 docs/source/siteadmin/codebase.rst create mode 100644 docs/source/siteadmin/configuration.rst create mode 100644 docs/source/siteadmin/deploying.rst create mode 100644 docs/source/siteadmin/foreword.rst create mode 100644 docs/source/siteadmin/help.rst create mode 100644 docs/source/siteadmin/media-types.rst create mode 100644 docs/source/siteadmin/plugins.rst create mode 100644 docs/source/siteadmin/production-deployments.rst create mode 100644 docs/source/siteadmin/relnotes.rst create mode 100644 docs/source/siteadmin/theming.rst delete mode 100644 docs/source/snugglygoblin.png delete mode 100644 docs/source/theming.rst (limited to 'docs/source') diff --git a/docs/source/_static/goblin.png b/docs/source/_static/goblin.png new file mode 100644 index 00000000..e20265e6 Binary files /dev/null and b/docs/source/_static/goblin.png differ diff --git a/docs/source/_static/snugglygoblin.png b/docs/source/_static/snugglygoblin.png new file mode 100644 index 00000000..f325ae4b Binary files /dev/null and b/docs/source/_static/snugglygoblin.png differ diff --git a/docs/source/about.rst b/docs/source/about.rst deleted file mode 100644 index 95647abb..00000000 --- a/docs/source/about.rst +++ /dev/null @@ -1,101 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - . - -======================= - About GNU MediaGoblin -======================= - -.. contents:: Sections - :local: - - -What is GNU MediaGoblin? -======================== - -In 2008, a number of free software developers and activists gathered -at the FSF to attempt to answer the question "What should software -freedom look like on the participatory web?" Their answer, the -`Franklin Street Statement`_ has lead to the development of -`autonomo.us`_ community, and free software projects including -`Identi.ca`_ and `Libre.fm`_. - -.. _Franklin Street Statement: http://autonomo.us/2008/07/franklin-street-statement/ -.. _autonomo.us: http://autonomo.us/ -.. _identi.ca: http://identi.ca/ -.. _Libre.fm: http://libre.fm/ - -Identi.ca and Libre.fm address the need for micro-blogging and music -sharing services and software that respect users' freedom and -autonomy. GNU MediaGoblin emerges from this milieu to create a -platform for us to share photos in an environment that respects our -freedom and independence. In the future MediaGoblin will include -support other media, like video, and provide tools to facilitate -collaboration on media projects. - - -Why Build GNU MediaGoblin? -========================== - -The Internet is designed---and works best---as a complex and endlessly -resilient network. When key services and media outlets are -concentrated in centralized platforms, the network becomes less useful -and increasingly fragile. As always, the proprietary nature of these -systems, hinders users ability to develop, extend, and understand -their software; however, in the case of network services it also means -that users must forfeit control of their data to the service -providers. - -Therefore, we believe that network services must be federated to avoid -centralization and that everyone ought to have control over their -data. In support of this, we've decided to help build the tools to -make these kinds of services possible. We hope you'll join us, both -as users and as contributors. - - -Who Contributes to the Project? -=============================== - -You do! - -We are free software activists and folks who have worked on a variety -of other projects including: Libre.fm, GNU Social, Status.net, Miro, -Miro Community, and OpenHatch among others. We're programmers, -musicians, writers, and painters. We're friendly and dedicated to -software and network freedom. - - -How Can I Participate? -====================== - -See `Get Involved `_ on the website. We -eagerly look forward to seeing you! - - -How is GNU MediaGoblin licensed? -================================ - -GNU MediaGoblin software is released under an AGPLv3 license. - -See the ``COPYING`` file in the root of the source for details. - - -Is MediaGoblin an official GNU project? What does that mean? -============================================================= - -MediaGoblin is an official GNU project! This status means that we the -meet the GNU Project's rigorous standards for free software. To find -out more about what that means, check out the `GNU website`_. - -Please feel free to contact us with further questions! - -.. _GNU website: http://gnu.org/ diff --git a/docs/source/codebase.rst b/docs/source/codebase.rst deleted file mode 100644 index 3ef91290..00000000 --- a/docs/source/codebase.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - . - -.. _codebase-chapter: - -======================== - Codebase Documentation -======================== - -.. contents:: Sections - :local: - - -This chapter covers the libraries that GNU MediaGoblin uses as well as -various recipes for getting things done. - -.. Note:: - - This chapter is in flux. Clearly there are things here that aren't - documented. If there's something you have questions about, please - ask! - - See `the join page on the website `_ - for where we hang out. - -For more information on how to get started hacking on GNU MediaGoblin, -see `the wiki `_. - - -Software Stack -============== - -* Project infrastructure - - * `Python `_: the language we're using to write - this - - * `Nose `_: - for unit tests - - * `virtualenv `_: for setting up an - isolated environment to keep mediagoblin and related packages - (potentially not required if MediaGoblin is packaged for your - distro) - -* Data storage - - * `SQLAlchemy `_: SQL ORM and database - interaction library for Python. Currently we support sqlite and - postgress as backends. - -* Web application - - * `Paste Deploy `_ and - `Paste Script `_: we'll use this for - configuring and launching the application - - * `WebOb `_: nice abstraction layer - from HTTP requests, responses and WSGI bits - - * `Routes `_: for URL routing - - * `Beaker `_: for handling sessions and - caching - - * `Jinja2 `_: the templating engine - - * `WTForms `_: for handling, - validation, and abstraction from HTML forms - - * `Celery `_: for task queuing (resizing - images, encoding video, ...) - - * `Babel `_: Used to extract and compile - translations. - - * `Markdown (for python) `_: - implementation of `Markdown `_ - text-to-html tool to make it easy for people to write richtext - comments, descriptions, and etc. - - * `lxml `_: nice xml and html processing for - python. - -* Media processing libraries - - * `Python Imaging Library `_: - used to resize and otherwise convert images for display. - - * `GStreamer `_: (Optional, for - video hosting sites only) Used to transcode video, and in the - future, probably audio too. - - * `chardet `_: (Optional, for - ascii art hosting sites only) Used to make ascii art thumbnails. - -* Front end - - * `JQuery `_: for groovy JavaScript things - - - -What's where -============ - -After you've run checked out mediagoblin and followed the virtualenv -instantiation instructions, you're faced with the following directory -tree:: - - mediagoblin/ - |- mediagoblin/ # source code - | |- tests/ - | |- templates/ - | |- auth/ - | \- submit/ - |- docs/ # documentation - |- devtools/ # some scripts for developer convenience - | - | # the below directories are installed into your virtualenv checkout - | - |- bin/ # scripts - |- develop-eggs/ - |- lib/ # python libraries installed into your virtualenv - |- include/ - |- mediagoblin.egg-info/ - |- parts/ - |- user_dev/ # sessions, etc - - -As you can see, all the code for GNU MediaGoblin is in the -``mediagoblin`` directory. - -Here are some interesting files and what they do: - -:routing.py: maps url paths to views -:views.py: views handle http requests -:models.py: holds the sqlalchemy schemas---these are the data structures - we're working with - -You'll notice that there are several sub-directories: tests, -templates, auth, submit, ... - -``tests`` holds the unit test code. - -``templates`` holds all the templates for the output. - -``auth`` and ``submit`` are modules that enacpsulate authentication -and media item submission. If you look in these directories, you'll -see they have their own ``routing.py``, ``view.py``, and -``models.py`` in addition to some other code. diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst deleted file mode 100644 index a3dafa4c..00000000 --- a/docs/source/configuration.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - . - -.. _configuration-chapter: - -======================== -Configuring MediaGoblin -======================== - -So! You've got MediaGoblin up and running, but you need to adjust -some configuration parameters. Well you've come to the right place! - - -MediaGoblin's config files -========================== - -When configuring MediaGoblin, there are two files you might want to -make local modified versions of, and one extra file that might be -helpful to look at. Let's examine these. - -mediagoblin.ini - This is the config file for MediaGoblin, the application. If you want to - tweak settings for MediaGoblin, you'll usually tweak them here. - -paste.ini - This is primarily a server configuration file, on the Python side - (specifically, on the WSGI side, via `paste deploy - `_ / `paste script - `_). It also sets up some - middleware that you can mostly ignore, except to configure - sessions... more on that later. If you are adding a different - Python server other than fastcgi / plain HTTP, you might configure - it here. You probably won't need to change this file very much. - - -There's one more file that you certainly won't change unless you're -making coding contributions to mediagoblin, but which can be useful to -read and reference: - -mediagoblin/config_spec.ini - This file is actually a specification for mediagoblin.ini itself, as - a config file! It defines types and defaults. Sometimes it's a - good place to look for documentation... or to find that hidden - option that we didn't tell you about. :) - - -Making local copies -=================== - -Let's assume you're doing the virtualenv setup described elsewhere in this -manual, and you need to make local tweaks to the config files. How do you do -that? Let's see. - -To make changes to mediagoblin.ini :: - - cp mediagoblin.ini mediagoblin_local.ini - -To make changes to paste.ini :: - - cp paste.ini paste_local.ini - -From here you should be able to make direct adjustments to the files, -and most of the commands described elsewhere in this manual will "notice" -your local config files and use those instead of the non-local version. - -.. note:: - - Note that all commands provide a way to pass in a specific config - file also, usually by a ``-cf`` flag. - - -Common changes -============== - -Enabling email notifications ----------------------------- - -You'll almost certainly want to enable sending email. By default, -MediaGoblin doesn't really do this... for the sake of developer -convenience, it runs in "email debug mode". - -To make MediaGoblin send email, you need a mailer daemon. - -Change this in your ``mediagoblin.ini`` file:: - - email_debug_mode = false - -You should also change the "from" email address by setting -``email_sender_address``. For example:: - - email_sender_address = "foo@example.com" - -If you have more custom SMTP settings, you also have the following -options at your disposal, which are all optional, and do exactly what -they sound like. - -- email_smtp_host -- email_smtp_port -- email_smtp_user -- email_smtp_pass - - -All other configuration changes -------------------------------- - -To be perfectly honest, there are quite a few options and we haven't had -time to document them all. - -So here's a cop-out section saying that if you get into trouble, hop -onto IRC and we'll help you out:: - - #mediagoblin on irc.freenode.net - - -Celery -====== - -We should point to another celery-specific section of the document -actually :) diff --git a/docs/source/deploying.rst b/docs/source/deploying.rst deleted file mode 100644 index 788b06d7..00000000 --- a/docs/source/deploying.rst +++ /dev/null @@ -1,320 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - . - -.. _deploying-chapter: - -===================== -Deploying MediaGoblin -===================== - -GNU MediaGoblin is fairly new and so at the time of writing, there -aren't easy package-manager-friendly methods to install MediaGoblin. -However, doing a basic install isn't too complex in and of itself. - -There's an almost infinite way to deploy things... for now, we'll keep -it simple with some assumptions and use a setup that combines -mediagoblin + virtualenv + fastcgi + nginx on a .deb or .rpm based -GNU/Linux distro. - -.. note:: - - These tools are for site administrators wanting to deploy a fresh - install. If instead you want to join in as a contributor, see our - `Hacking HOWTO `_ instead. - -Prepare System --------------- - -Dependencies -~~~~~~~~~~~~ - -MediaGoblin has the following core dependencies: - -- Python 2.6 or 2.7 -- `python-lxml `_ -- `git `_ -- `SQLite `_/`PostgreSQL `_ -- `Python Imaging Library `_ (PIL) -- `virtualenv `_ - -On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and -derivatives) issue the following command:: - - sudo apt-get install git-core python python-dev python-lxml \ - python-imaging python-virtualenv - -On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the -following command:: - - yum install python-paste-deploy python-paste-script \ - git-core python python-devel python-lxml python-imaging \ - python-virtualenv - -Configure PostgreSQL -~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - MediaGoblin currently supports PostgreSQL and SQLite. The default is a - local SQLite database. This will "just work" for small deployments. - - For medium to large deployments we recommend PostgreSQL. - - If you don't want/need postgres, skip this section. - -These are the packages needed for Debian Wheezy (testing):: - - sudo apt-get install postgresql postgresql-client python-psycopg2 - -The installation process will create a new *system* user named ``postgres``, -it will have privilegies sufficient to manage the database. We will create a -new database user with restricted privilegies and a new database owned by our -restricted database user for our MediaGoblin instance. - -In this example, the database user will be ``mediagoblin`` and the database -name will be ``mediagoblin`` too. - -To create our new user, run:: - - sudo -u postgres createuser mediagoblin - -then answer NO to *all* the questions:: - - Shall the new role be a superuser? (y/n) n - Shall the new role be allowed to create databases? (y/n) n - Shall the new role be allowed to create more new roles? (y/n) n - -then create the database all our MediaGoblin data should be stored in:: - - sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin - -where the first ``mediagoblin`` is the database owner and the second -``mediagoblin`` is the database name. - -.. caution:: Where is the password? - - These steps enable you to authenticate to the database in a password-less - manner via local UNIX authentication provided you run the MediaGoblin - application as a user with the same name as the user you created in - PostgreSQL. - - More on this in :ref:`Drop Privileges for MediaGoblin `. - - -.. _drop-privileges-for-mediagoblin: - -Drop Privileges for MediaGoblin -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As MediaGoblin does not require special permissions or elevated -access, you should run MediaGoblin under an existing non-root user or -preferably create a dedicated user for the purpose of running -MediaGoblin. Consult your distribution's documentation on how to -create "system account" or dedicated service user. Ensure that it is -not possible to log in to your system with as this user. - -You should create a working directory for MediaGoblin. This document -assumes your local git repository will be located at -``/srv/mediagoblin.example.org/mediagoblin/`` for this documentation. -Substitute your prefer ed local deployment path as needed. - -This document assumes that all operations are performed as this -user. To drop privileges to this user, run the following command:: - - su - [mediagoblin] - -Where, "``[mediagoblin]``" is the username of the system user that will -run MediaGoblin. - -Install MediaGoblin and Virtualenv ----------------------------------- - -.. note:: - - MediaGoblin is still developing rapidly. As a result - the following instructions recommend installing from the ``master`` - branch of the git repository. Eventually production deployments will - want to transition to running from more consistent releases. - -Issue the following commands, to create and change the working -directory. Modify these commands to reflect your own environment:: - - mkdir -p /srv/mediagoblin.example.org/ - cd /srv/mediagoblin.example.org/ - -Clone the MediaGoblin repository:: - - git clone git://gitorious.org/mediagoblin/mediagoblin.git - -And set up the in-package virtualenv:: - - cd mediagoblin - (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop - -.. note:: - - If you have problems here, consider trying to install virtualenv - with the ``--distribute`` or ``--no-site-packages`` options. If - your system's default Python is in the 3.x series you man need to - run ``virtualenv`` with the ``--python=python2.7`` or - ``--python=python2.6`` options. - -The above provides an in-package install of ``virtualenv``. While this -is counter to the conventional ``virtualenv`` configuration, it is -more reliable and considerably easier to configure and illustrate. If -you're familiar with Python packaging you may consider deploying with -your preferred the method. - -Assuming you are going to deploy with FastCGI, you should also install -flup:: - - ./bin/easy_install flup - -This concludes the initial configuration of the development -environment. In the future, you want update your -codebase, you should also run:: - - ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate - -Deploy MediaGoblin Services ---------------------------- - -Configure MediaGoblin to use the PostgreSQL database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you are using postgres, edit the ``[mediagoblin]`` section in your -``mediagoblin_local.ini`` and put in:: - - sql_engine = postgresql:///mediagoblin - -if you are running the MediaGoblin application as the same 'user' as the -database owner. - - -Update database data structures -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before you start using the database, you need to run:: - - ./bin/gmg dbupdate - -to populate the database with the MediaGoblin data structures. - - -Test the Server -~~~~~~~~~~~~~~~ - -At this point MediaGoblin should be properly installed. You can -test the deployment with the following command:: - - ./lazyserver.sh --server-name=broadcast - -You should be able to connect to the machine on port 6543 in your -browser to confirm that the service is operable. - -Connect the Webserver to MediaGoblin with FastCGI -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section describes how to configure MediaGoblin to work via -FastCGI. Our configuration example will use nginx, however, you may -use any webserver of your choice as long as it supports the FastCGI -protocol. If you do not already have a web server, consider nginx, as -the configuration files may be more clear than the -alternatives. - -Create a configuration file at -``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link -into a directory that will be included in your ``nginx`` configuration -(e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with -one of the following commands (as the root user):: - - ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/ - ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/ - -Modify these commands and locations depending on your preferences and -the existing configuration of your nginx instance. The contents of -this ``nginx.conf`` file should be modeled on the following:: - - server { - ################################################# - # Stock useful config options, but ignore them :) - ################################################# - include /etc/nginx/mime.types; - - autoindex off; - default_type application/octet-stream; - sendfile on; - - # Gzip - gzip on; - gzip_min_length 1024; - gzip_buffers 4 32k; - gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; - - ##################################### - # Mounting MediaGoblin stuff - # This is the section you should read - ##################################### - - # Change this to update the upload size limit for your users - client_max_body_size 8m; - - server_name mediagoblin.example.org www.mediagoblin.example.org; - access_log /var/log/nginx/mediagoblin.example.access.log; - error_log /var/log/nginx/mediagoblin.example.error.log; - - # MediaGoblin's stock static files: CSS, JS, etc. - location /mgoblin_static/ { - alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/; - } - - # Instance specific media: - location /mgoblin_media/ { - alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; - } - - # Mounting MediaGoblin itself via FastCGI. - location / { - fastcgi_pass 127.0.0.1:26543; - include /etc/nginx/fastcgi_params; - - # our understanding vs nginx's handling of script_name vs - # path_info don't match :) - fastcgi_param PATH_INFO $fastcgi_script_name; - fastcgi_param SCRIPT_NAME ""; - } - } - -Now, nginx instance is configured to serve the MediaGoblin -application. Perform a quick test to ensure that this configuration -works. Restart nginx so it picks up your changes, with a command that -resembles one of the following (as the root user):: - - sudo /etc/init.d/nginx restart - sudo /etc/rc.d/nginx restart - -Now start MediaGoblin. Use the following command sequence as an -example:: - - cd /srv/mediagoblin.example.org/mediagoblin/ - ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 - -Visit the site you've set up in your browser by visiting -. You should see MediaGoblin! - -.. note:: - - The configuration described above is sufficient for development and - smaller deployments. However, for larger production deployments - with larger processing requirements, see the - ":doc:`production-deployments`" documentation. diff --git a/docs/source/foreword.rst b/docs/source/foreword.rst deleted file mode 100644 index 39ece25d..00000000 --- a/docs/source/foreword.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - . - -======== -Foreword -======== - -About the MediaGoblin Manual -============================ - -This is the site administrator manual for MediaGoblin. It covers how -to set up and configure MediaGoblin and the kind of information that -someone running MediaGoblin would need to know. - -We have other documentation at: - -* http://mediagoblin.org/join/ for general "join us" information -* http://wiki.mediagoblin.org/ for our contributor/developer-focused wiki - - -Improving the MediaGoblin Manual -================================ - -There are a few ways---please pick whichever method is convenient for -you! - -1. Write up a bug report in the bug tracker -2. Tell someone on IRC ``#mediagoblin`` on Freenode. -3. Write an email to the devel mailing list. - -Information about the bugtracker, IRC and the mailing list is all on -the `join page`_. - -.. _join page: http://mediagoblin.org/join/ - -Patches are the most helpful, but even feedback on what you think -could be improved and how to improve it is also helpful. - diff --git a/docs/source/goblin.png b/docs/source/goblin.png deleted file mode 100644 index e20265e6..00000000 Binary files a/docs/source/goblin.png and /dev/null differ diff --git a/docs/source/help.rst b/docs/source/help.rst deleted file mode 100644 index 4b584ac1..00000000 --- a/docs/source/help.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - . - -================================== - How to Get Help with MediaGoblin -================================== - -There are a couple of ways to get help with problems with MediaGoblin: - -1. ask for help on IRC - -2. ask for help on the devel mailing list - -Details for both IRC and the mailing list are on the `join page`_ of the -website. - -.. _join page: http://mediagoblin.org/join/ - - diff --git a/docs/source/index.rst b/docs/source/index.rst index 187a0382..dc8bacc7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -11,29 +11,42 @@ Dedication along with this software. If not, see . -.. 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: +Part 1: Site Administrator's Guide +================================== + +This guide covers installing, configuring, deploying and running a GNU +MediaGoblin website. It is written for site administrators. .. toctree:: - :maxdepth: 2 - - foreword - about - deploying - production-deployments - configuration - media-types - help - relnotes - theming - codebase + :maxdepth: 1 + + siteadmin/foreword + siteadmin/about + siteadmin/deploying + siteadmin/production-deployments + siteadmin/configuration + siteadmin/media-types + siteadmin/help + siteadmin/relnotes + siteadmin/theming + siteadmin/plugins + siteadmin/codebase + + +Part 2: Plugin Writer's Guide +============================= + +This guide covers writing new GNU MediaGoblin plugins. + +.. toctree:: + :maxdepth: 1 + + pluginwriter/foreward Indices and tables diff --git a/docs/source/media-types.rst b/docs/source/media-types.rst deleted file mode 100644 index 1cf7f30c..00000000 --- a/docs/source/media-types.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - . - -.. _media-types-chapter: - -==================== -Enabling Media Types -==================== - -In the future, there will be all sorts of media types you can enable, -but in the meanwhile there are two additional media type: video and -ascii art. - -First, you should probably read ":doc:`configuration`" to make sure -you know how to modify the mediagoblin config file. - -Video -===== - -To enable video, first install gstreamer and the python-gstreamer -bindings (as well as whatever gstremaer extensions you want, -good/bad/ugly). On Debianoid systems:: - - sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \ - gstreamer0.10-ffmpeg - -Next, modify (and possibly copy over from ``mediagoblin.ini``) your -``mediagoblin_local.ini``. In the ``[mediagoblin]`` section, add -``mediagoblin.media_types.video`` to the ``media_types`` list. - -For example, if your system supported image and video media types, then -the list would look like this:: - - media_types = mediagoblin.media_types.image, mediagoblin.media_types.video - -Now you should be able to submit videos, and mediagoblin should -transcode them. - -.. note:: - - You almost certainly want to separate Celery from the normal - paste process or your users will probably find that their connections - time out as the video transcodes. To set that up, check out the - ":doc:`production-deployments`" section of this manual. - - -Ascii art -========= - -To enable ascii art support, first install the -`chardet `_ -library, which is necessary for creating thumbnails of ascii art:: - - ./bin/easy_install chardet - - -Next, modify (and possibly copy over from ``mediagoblin.ini``) your -``mediagoblin_local.ini``. In the ``[mediagoblin]`` section, add -``mediagoblin.media_types.ascii`` to the ``media_types`` list. - -For example, if your system supported image and ascii art media types, then -the list would look like this:: - - media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii - -Now any .txt file you uploaded will be processed as ascii art! diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst deleted file mode 100644 index dfb69075..00000000 --- a/docs/source/plugins.rst +++ /dev/null @@ -1,137 +0,0 @@ -========= - Plugins -========= - -GNU MediaGoblin supports plugins that allow you to augment MediaGoblin's -behavior. - -This chapter covers discovering, installing, configuring and removing -plugins. - - -Discovering plugins -=================== - -MediaGoblin comes with core plugins. Core plugins are located in the -``mediagoblin.plugins`` module of the MediaGoblin code. Because they -come with MediaGoblin, you don't have to install them, but you do have -to add them to your config file if you're interested in using them. - -You can also write your own plugins and additionally find plugins -elsewhere on the Internet. Once you find a plugin you like, you need -to first install it, then add it to your configuration. - -.. todo:: how do you find plugins on the internet? - - -Installing plugins -================== - -Core plugins ------------- - -MediaGoblin core plugins don't need to be installed because they come -with MediaGoblin. Further, when you upgrade MediaGoblin, you will also -get updates to the core plugins. - - -Other plugins -------------- - -If the plugin is available on the `Python Package Index -`_, then you can install the plugin with pip:: - - pip install - -For example, if we wanted to install the plugin named -"mediagoblin-restrictfive", we would do:: - - pip install mediagoblin-restrictfive - -.. Note:: - - If you're using a virtual environment, make sure to activate the - virtual environment before installing with pip. Otherwise the - plugin may get installed in a different environment than the one - MediaGoblin is installed in. - -Once you've installed the plugin software, you need to tell -MediaGoblin that this is a plugin you want MediaGoblin to use. To do -that, you edit the ``mediagoblin.ini`` file and add the plugin as a -subsection of the plugin section. - -For example, say the "mediagoblin-restrictfive" plugin had the Python -package path ``restrictfive``, then you would add ``restrictfive`` to -the ``plugins`` section as a subsection:: - - [plugins] - - [[restrictfive]] - - -Configuring plugins -=================== - -Configuration for a plugin goes in the subsection for that plugin. Core -plugins are documented in the administration guide. Other plugins -should come with documentation that tells you how to configure them. - -Example 1: Core MediaGoblin plugin - -If you wanted to use the core MediaGoblin flatpages plugin, the module -for that is ``mediagoblin.plugins.flatpages`` and you would add that -to your ``.ini`` file like this:: - - [plugins] - - [[mediagoblin.plugins.flatpages]] - # configuration for flatpages plugin here! - directory = /srv/mediagoblin/flatpages - -Example 2: Plugin that is not a core MediaGoblin plugin - -If you installed a hypothetical restrictfive plugin which is in the -module ``restrictfive``, your ``.ini`` file might look like this (with -comments making the bits clearer):: - - [plugins] - - [[restrictfive]] - # configuration for restrictfive here! - -Check the plugin's documentation for what configuration options are -available. - - -Removing plugins -================ - -To remove a plugin, use ``pip uninstall``. For example:: - - pip uninstall mediagoblin-restrictfive - -.. Note:: - - If you're using a virtual environment, make sure to activate the - virtual environment before uninstalling with pip. Otherwise the - plugin may get installed in a different environment. - - -Upgrading plugins -================= - -Core plugins ------------- - -Core plugins get upgraded automatically when you upgrade MediaGoblin -because they come with MediaGoblin. - - -Other plugins -------------- - -For plugins that you install with pip, you can upgrade them with pip:: - - pip install -U - -The ``-U`` tells pip to upgrade the package. diff --git a/docs/source/pluginwriter/foreward.rst b/docs/source/pluginwriter/foreward.rst new file mode 100644 index 00000000..fd3a0c22 --- /dev/null +++ b/docs/source/pluginwriter/foreward.rst @@ -0,0 +1,43 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +======== +Foreword +======== + +About the Plugin Writer's Guide +=============================== + +This guide covers writing plugins for GNU MediaGoblin. It's very much +a work in progress partially because we just started writing it and +partially because the plugin API is currently in flux. + + +Improving the Plugin Writer's Guide +=================================== + +There are a few ways---please pick whichever method is convenient for +you! + +1. Write up a bug report in the bug tracker +2. Tell someone on IRC ``#mediagoblin`` on Freenode. +3. Write an email to the devel mailing list. + +Information about the bugtracker, IRC and the mailing list is all on +the `join page`_. + +.. _join page: http://mediagoblin.org/join/ + +Patches are the most helpful, but even feedback on what you think +could be improved and how to improve it is also helpful. + diff --git a/docs/source/production-deployments.rst b/docs/source/production-deployments.rst deleted file mode 100644 index 1e6631db..00000000 --- a/docs/source/production-deployments.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - . - -========================================= -Considerations for Production Deployments -========================================= - -This document contains a number of suggestions for deploying -MediaGoblin in actual production environments. Consider -":doc:`deploying`" for a basic overview of how to deploy MediaGoblin. - -Deploy with Paste ------------------ - -The instance configured with ``./lazyserver.sh`` is not ideal for a -production MediaGoblin deployment. Ideally, you should be able to use -an "init" or "control" script to launch and restart the MediaGoblin -process. - -Use the following command as the basis for such a script: :: - - CELERY_ALWAYS_EAGER=true \ - /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ - /srv/mediagoblin.example.org/mediagoblin/paste.ini \ - --pid-file=/var/run/mediagoblin.pid \ - --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 - -The above configuration places MediaGoblin in "always eager" mode -with Celery, this means that submissions of content will be processed -synchronously, and the user will advance to the next page only after -processing is complete. If we take Celery out of "always eager mode," -the user will be able to immediately return to the MediaGoblin site -while processing is ongoing. In these cases, use the following command -as the basis for your script: :: - - CELERY_ALWAYS_EAGER=false \ - /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ - /srv/mediagoblin.example.org/mediagoblin/paste.ini \ - --pid-file=/var/run/mediagoblin.pid \ - --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 - -Separate Celery ---------------- - -While the ``./lazyserer.sh`` configuration provides an efficient way to -start using a MediaGoblin instance, it is not suitable for production -deployments for several reasons: - -In nearly every scenario, work on the Celery queue will need to -balance with the demands of other processes, and cannot proceed -synchronously. This is a particularly relevant problem if you use -MediaGoblin to host video content. Processing with Celery ought to be -operationally separate from the MediaGoblin application itself, this -simplifies management and support better workload distribution. - -Basically, if you're doing anything beyond a trivial workload, such as -image hosting for a small set of users, or have limited media types -such as "ASCII art" or icon sharing, you will need to run ``celeryd`` -as a separate process. - -Build an :ref:`init script ` around the following -command:: - - CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd - -Modify your existing MediaGoblin and application init scripts, if -necessary, to prevent them from starting their own ``celeryd`` -processes. - -.. _init-script: - -Use an Init Script ------------------- - -Look in your system's ``/etc/init.d/`` or ``/etc/rc.d/`` directory for -examples of how to build scripts that will start, stop, and restart -MediaGoblin and Celery. These scripts will vary by -distribution/operating system. In the future, MediaGoblin will provide -example scripts as examples. - -.. TODO insert init script here -.. TODO are additional concerns ? - .. Other Concerns - .. -------------- diff --git a/docs/source/relnotes.rst b/docs/source/relnotes.rst deleted file mode 100644 index 2efded73..00000000 --- a/docs/source/relnotes.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - . - -============= -Release Notes -============= - -This chapter has important information for releases in it. -If you're upgrading from a previous release, please read it -carefully, or at least skim over it. - - -0.3.0 -===== - -This release has one important change. You need to act when -upgrading from a previous version! - -This release changes the database system from MongoDB to -SQL(alchemy). If you want to setup a fresh instance, just -follow the instructions in the deployment chapter. If on -the other hand you want to continue to use one instance, -read on. - -To convert your data from MongoDB to SQL(alchemy), you need -to follow these steps: - -1. Make sure your MongoDB is still running and has your - data, it's needed for the conversion. - -2. Configure the ``sql_engine`` URI in the config to represent - your target database (see: :ref:`deploying-chapter`) - -3. You need an empty database. - -4. Then run the following command:: - - bin/gmg [-cf mediagoblin_config.ini] convert_mongo_to_sql - -5. Start your server and investigate. - -6. That's it. diff --git a/docs/source/siteadmin/about.rst b/docs/source/siteadmin/about.rst new file mode 100644 index 00000000..95647abb --- /dev/null +++ b/docs/source/siteadmin/about.rst @@ -0,0 +1,101 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +======================= + About GNU MediaGoblin +======================= + +.. contents:: Sections + :local: + + +What is GNU MediaGoblin? +======================== + +In 2008, a number of free software developers and activists gathered +at the FSF to attempt to answer the question "What should software +freedom look like on the participatory web?" Their answer, the +`Franklin Street Statement`_ has lead to the development of +`autonomo.us`_ community, and free software projects including +`Identi.ca`_ and `Libre.fm`_. + +.. _Franklin Street Statement: http://autonomo.us/2008/07/franklin-street-statement/ +.. _autonomo.us: http://autonomo.us/ +.. _identi.ca: http://identi.ca/ +.. _Libre.fm: http://libre.fm/ + +Identi.ca and Libre.fm address the need for micro-blogging and music +sharing services and software that respect users' freedom and +autonomy. GNU MediaGoblin emerges from this milieu to create a +platform for us to share photos in an environment that respects our +freedom and independence. In the future MediaGoblin will include +support other media, like video, and provide tools to facilitate +collaboration on media projects. + + +Why Build GNU MediaGoblin? +========================== + +The Internet is designed---and works best---as a complex and endlessly +resilient network. When key services and media outlets are +concentrated in centralized platforms, the network becomes less useful +and increasingly fragile. As always, the proprietary nature of these +systems, hinders users ability to develop, extend, and understand +their software; however, in the case of network services it also means +that users must forfeit control of their data to the service +providers. + +Therefore, we believe that network services must be federated to avoid +centralization and that everyone ought to have control over their +data. In support of this, we've decided to help build the tools to +make these kinds of services possible. We hope you'll join us, both +as users and as contributors. + + +Who Contributes to the Project? +=============================== + +You do! + +We are free software activists and folks who have worked on a variety +of other projects including: Libre.fm, GNU Social, Status.net, Miro, +Miro Community, and OpenHatch among others. We're programmers, +musicians, writers, and painters. We're friendly and dedicated to +software and network freedom. + + +How Can I Participate? +====================== + +See `Get Involved `_ on the website. We +eagerly look forward to seeing you! + + +How is GNU MediaGoblin licensed? +================================ + +GNU MediaGoblin software is released under an AGPLv3 license. + +See the ``COPYING`` file in the root of the source for details. + + +Is MediaGoblin an official GNU project? What does that mean? +============================================================= + +MediaGoblin is an official GNU project! This status means that we the +meet the GNU Project's rigorous standards for free software. To find +out more about what that means, check out the `GNU website`_. + +Please feel free to contact us with further questions! + +.. _GNU website: http://gnu.org/ diff --git a/docs/source/siteadmin/codebase.rst b/docs/source/siteadmin/codebase.rst new file mode 100644 index 00000000..3ef91290 --- /dev/null +++ b/docs/source/siteadmin/codebase.rst @@ -0,0 +1,160 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +.. _codebase-chapter: + +======================== + Codebase Documentation +======================== + +.. contents:: Sections + :local: + + +This chapter covers the libraries that GNU MediaGoblin uses as well as +various recipes for getting things done. + +.. Note:: + + This chapter is in flux. Clearly there are things here that aren't + documented. If there's something you have questions about, please + ask! + + See `the join page on the website `_ + for where we hang out. + +For more information on how to get started hacking on GNU MediaGoblin, +see `the wiki `_. + + +Software Stack +============== + +* Project infrastructure + + * `Python `_: the language we're using to write + this + + * `Nose `_: + for unit tests + + * `virtualenv `_: for setting up an + isolated environment to keep mediagoblin and related packages + (potentially not required if MediaGoblin is packaged for your + distro) + +* Data storage + + * `SQLAlchemy `_: SQL ORM and database + interaction library for Python. Currently we support sqlite and + postgress as backends. + +* Web application + + * `Paste Deploy `_ and + `Paste Script `_: we'll use this for + configuring and launching the application + + * `WebOb `_: nice abstraction layer + from HTTP requests, responses and WSGI bits + + * `Routes `_: for URL routing + + * `Beaker `_: for handling sessions and + caching + + * `Jinja2 `_: the templating engine + + * `WTForms `_: for handling, + validation, and abstraction from HTML forms + + * `Celery `_: for task queuing (resizing + images, encoding video, ...) + + * `Babel `_: Used to extract and compile + translations. + + * `Markdown (for python) `_: + implementation of `Markdown `_ + text-to-html tool to make it easy for people to write richtext + comments, descriptions, and etc. + + * `lxml `_: nice xml and html processing for + python. + +* Media processing libraries + + * `Python Imaging Library `_: + used to resize and otherwise convert images for display. + + * `GStreamer `_: (Optional, for + video hosting sites only) Used to transcode video, and in the + future, probably audio too. + + * `chardet `_: (Optional, for + ascii art hosting sites only) Used to make ascii art thumbnails. + +* Front end + + * `JQuery `_: for groovy JavaScript things + + + +What's where +============ + +After you've run checked out mediagoblin and followed the virtualenv +instantiation instructions, you're faced with the following directory +tree:: + + mediagoblin/ + |- mediagoblin/ # source code + | |- tests/ + | |- templates/ + | |- auth/ + | \- submit/ + |- docs/ # documentation + |- devtools/ # some scripts for developer convenience + | + | # the below directories are installed into your virtualenv checkout + | + |- bin/ # scripts + |- develop-eggs/ + |- lib/ # python libraries installed into your virtualenv + |- include/ + |- mediagoblin.egg-info/ + |- parts/ + |- user_dev/ # sessions, etc + + +As you can see, all the code for GNU MediaGoblin is in the +``mediagoblin`` directory. + +Here are some interesting files and what they do: + +:routing.py: maps url paths to views +:views.py: views handle http requests +:models.py: holds the sqlalchemy schemas---these are the data structures + we're working with + +You'll notice that there are several sub-directories: tests, +templates, auth, submit, ... + +``tests`` holds the unit test code. + +``templates`` holds all the templates for the output. + +``auth`` and ``submit`` are modules that enacpsulate authentication +and media item submission. If you look in these directories, you'll +see they have their own ``routing.py``, ``view.py``, and +``models.py`` in addition to some other code. diff --git a/docs/source/siteadmin/configuration.rst b/docs/source/siteadmin/configuration.rst new file mode 100644 index 00000000..a3dafa4c --- /dev/null +++ b/docs/source/siteadmin/configuration.rst @@ -0,0 +1,129 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +.. _configuration-chapter: + +======================== +Configuring MediaGoblin +======================== + +So! You've got MediaGoblin up and running, but you need to adjust +some configuration parameters. Well you've come to the right place! + + +MediaGoblin's config files +========================== + +When configuring MediaGoblin, there are two files you might want to +make local modified versions of, and one extra file that might be +helpful to look at. Let's examine these. + +mediagoblin.ini + This is the config file for MediaGoblin, the application. If you want to + tweak settings for MediaGoblin, you'll usually tweak them here. + +paste.ini + This is primarily a server configuration file, on the Python side + (specifically, on the WSGI side, via `paste deploy + `_ / `paste script + `_). It also sets up some + middleware that you can mostly ignore, except to configure + sessions... more on that later. If you are adding a different + Python server other than fastcgi / plain HTTP, you might configure + it here. You probably won't need to change this file very much. + + +There's one more file that you certainly won't change unless you're +making coding contributions to mediagoblin, but which can be useful to +read and reference: + +mediagoblin/config_spec.ini + This file is actually a specification for mediagoblin.ini itself, as + a config file! It defines types and defaults. Sometimes it's a + good place to look for documentation... or to find that hidden + option that we didn't tell you about. :) + + +Making local copies +=================== + +Let's assume you're doing the virtualenv setup described elsewhere in this +manual, and you need to make local tweaks to the config files. How do you do +that? Let's see. + +To make changes to mediagoblin.ini :: + + cp mediagoblin.ini mediagoblin_local.ini + +To make changes to paste.ini :: + + cp paste.ini paste_local.ini + +From here you should be able to make direct adjustments to the files, +and most of the commands described elsewhere in this manual will "notice" +your local config files and use those instead of the non-local version. + +.. note:: + + Note that all commands provide a way to pass in a specific config + file also, usually by a ``-cf`` flag. + + +Common changes +============== + +Enabling email notifications +---------------------------- + +You'll almost certainly want to enable sending email. By default, +MediaGoblin doesn't really do this... for the sake of developer +convenience, it runs in "email debug mode". + +To make MediaGoblin send email, you need a mailer daemon. + +Change this in your ``mediagoblin.ini`` file:: + + email_debug_mode = false + +You should also change the "from" email address by setting +``email_sender_address``. For example:: + + email_sender_address = "foo@example.com" + +If you have more custom SMTP settings, you also have the following +options at your disposal, which are all optional, and do exactly what +they sound like. + +- email_smtp_host +- email_smtp_port +- email_smtp_user +- email_smtp_pass + + +All other configuration changes +------------------------------- + +To be perfectly honest, there are quite a few options and we haven't had +time to document them all. + +So here's a cop-out section saying that if you get into trouble, hop +onto IRC and we'll help you out:: + + #mediagoblin on irc.freenode.net + + +Celery +====== + +We should point to another celery-specific section of the document +actually :) diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst new file mode 100644 index 00000000..788b06d7 --- /dev/null +++ b/docs/source/siteadmin/deploying.rst @@ -0,0 +1,320 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +.. _deploying-chapter: + +===================== +Deploying MediaGoblin +===================== + +GNU MediaGoblin is fairly new and so at the time of writing, there +aren't easy package-manager-friendly methods to install MediaGoblin. +However, doing a basic install isn't too complex in and of itself. + +There's an almost infinite way to deploy things... for now, we'll keep +it simple with some assumptions and use a setup that combines +mediagoblin + virtualenv + fastcgi + nginx on a .deb or .rpm based +GNU/Linux distro. + +.. note:: + + These tools are for site administrators wanting to deploy a fresh + install. If instead you want to join in as a contributor, see our + `Hacking HOWTO `_ instead. + +Prepare System +-------------- + +Dependencies +~~~~~~~~~~~~ + +MediaGoblin has the following core dependencies: + +- Python 2.6 or 2.7 +- `python-lxml `_ +- `git `_ +- `SQLite `_/`PostgreSQL `_ +- `Python Imaging Library `_ (PIL) +- `virtualenv `_ + +On a DEB-based system (e.g Debian, gNewSense, Trisquel, Ubuntu, and +derivatives) issue the following command:: + + sudo apt-get install git-core python python-dev python-lxml \ + python-imaging python-virtualenv + +On a RPM-based system (e.g. Fedora, RedHat, and derivatives) issue the +following command:: + + yum install python-paste-deploy python-paste-script \ + git-core python python-devel python-lxml python-imaging \ + python-virtualenv + +Configure PostgreSQL +~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + MediaGoblin currently supports PostgreSQL and SQLite. The default is a + local SQLite database. This will "just work" for small deployments. + + For medium to large deployments we recommend PostgreSQL. + + If you don't want/need postgres, skip this section. + +These are the packages needed for Debian Wheezy (testing):: + + sudo apt-get install postgresql postgresql-client python-psycopg2 + +The installation process will create a new *system* user named ``postgres``, +it will have privilegies sufficient to manage the database. We will create a +new database user with restricted privilegies and a new database owned by our +restricted database user for our MediaGoblin instance. + +In this example, the database user will be ``mediagoblin`` and the database +name will be ``mediagoblin`` too. + +To create our new user, run:: + + sudo -u postgres createuser mediagoblin + +then answer NO to *all* the questions:: + + Shall the new role be a superuser? (y/n) n + Shall the new role be allowed to create databases? (y/n) n + Shall the new role be allowed to create more new roles? (y/n) n + +then create the database all our MediaGoblin data should be stored in:: + + sudo -u postgres createdb -E UNICODE -O mediagoblin mediagoblin + +where the first ``mediagoblin`` is the database owner and the second +``mediagoblin`` is the database name. + +.. caution:: Where is the password? + + These steps enable you to authenticate to the database in a password-less + manner via local UNIX authentication provided you run the MediaGoblin + application as a user with the same name as the user you created in + PostgreSQL. + + More on this in :ref:`Drop Privileges for MediaGoblin `. + + +.. _drop-privileges-for-mediagoblin: + +Drop Privileges for MediaGoblin +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As MediaGoblin does not require special permissions or elevated +access, you should run MediaGoblin under an existing non-root user or +preferably create a dedicated user for the purpose of running +MediaGoblin. Consult your distribution's documentation on how to +create "system account" or dedicated service user. Ensure that it is +not possible to log in to your system with as this user. + +You should create a working directory for MediaGoblin. This document +assumes your local git repository will be located at +``/srv/mediagoblin.example.org/mediagoblin/`` for this documentation. +Substitute your prefer ed local deployment path as needed. + +This document assumes that all operations are performed as this +user. To drop privileges to this user, run the following command:: + + su - [mediagoblin] + +Where, "``[mediagoblin]``" is the username of the system user that will +run MediaGoblin. + +Install MediaGoblin and Virtualenv +---------------------------------- + +.. note:: + + MediaGoblin is still developing rapidly. As a result + the following instructions recommend installing from the ``master`` + branch of the git repository. Eventually production deployments will + want to transition to running from more consistent releases. + +Issue the following commands, to create and change the working +directory. Modify these commands to reflect your own environment:: + + mkdir -p /srv/mediagoblin.example.org/ + cd /srv/mediagoblin.example.org/ + +Clone the MediaGoblin repository:: + + git clone git://gitorious.org/mediagoblin/mediagoblin.git + +And set up the in-package virtualenv:: + + cd mediagoblin + (virtualenv --system-site-packages . || virtualenv .) && ./bin/python setup.py develop + +.. note:: + + If you have problems here, consider trying to install virtualenv + with the ``--distribute`` or ``--no-site-packages`` options. If + your system's default Python is in the 3.x series you man need to + run ``virtualenv`` with the ``--python=python2.7`` or + ``--python=python2.6`` options. + +The above provides an in-package install of ``virtualenv``. While this +is counter to the conventional ``virtualenv`` configuration, it is +more reliable and considerably easier to configure and illustrate. If +you're familiar with Python packaging you may consider deploying with +your preferred the method. + +Assuming you are going to deploy with FastCGI, you should also install +flup:: + + ./bin/easy_install flup + +This concludes the initial configuration of the development +environment. In the future, you want update your +codebase, you should also run:: + + ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate + +Deploy MediaGoblin Services +--------------------------- + +Configure MediaGoblin to use the PostgreSQL database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are using postgres, edit the ``[mediagoblin]`` section in your +``mediagoblin_local.ini`` and put in:: + + sql_engine = postgresql:///mediagoblin + +if you are running the MediaGoblin application as the same 'user' as the +database owner. + + +Update database data structures +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before you start using the database, you need to run:: + + ./bin/gmg dbupdate + +to populate the database with the MediaGoblin data structures. + + +Test the Server +~~~~~~~~~~~~~~~ + +At this point MediaGoblin should be properly installed. You can +test the deployment with the following command:: + + ./lazyserver.sh --server-name=broadcast + +You should be able to connect to the machine on port 6543 in your +browser to confirm that the service is operable. + +Connect the Webserver to MediaGoblin with FastCGI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to configure MediaGoblin to work via +FastCGI. Our configuration example will use nginx, however, you may +use any webserver of your choice as long as it supports the FastCGI +protocol. If you do not already have a web server, consider nginx, as +the configuration files may be more clear than the +alternatives. + +Create a configuration file at +``/srv/mediagoblin.example.org/nginx.conf`` and create a symbolic link +into a directory that will be included in your ``nginx`` configuration +(e.g. "``/etc/nginx/sites-enabled`` or ``/etc/nginx/conf.d``) with +one of the following commands (as the root user):: + + ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/conf.d/ + ln -s /srv/mediagoblin.example.org/nginx.conf /etc/nginx/sites-enabled/ + +Modify these commands and locations depending on your preferences and +the existing configuration of your nginx instance. The contents of +this ``nginx.conf`` file should be modeled on the following:: + + server { + ################################################# + # Stock useful config options, but ignore them :) + ################################################# + include /etc/nginx/mime.types; + + autoindex off; + default_type application/octet-stream; + sendfile on; + + # Gzip + gzip on; + gzip_min_length 1024; + gzip_buffers 4 32k; + gzip_types text/plain text/html application/x-javascript text/javascript text/xml text/css; + + ##################################### + # Mounting MediaGoblin stuff + # This is the section you should read + ##################################### + + # Change this to update the upload size limit for your users + client_max_body_size 8m; + + server_name mediagoblin.example.org www.mediagoblin.example.org; + access_log /var/log/nginx/mediagoblin.example.access.log; + error_log /var/log/nginx/mediagoblin.example.error.log; + + # MediaGoblin's stock static files: CSS, JS, etc. + location /mgoblin_static/ { + alias /srv/mediagoblin.example.org/mediagoblin/mediagoblin/static/; + } + + # Instance specific media: + location /mgoblin_media/ { + alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; + } + + # Mounting MediaGoblin itself via FastCGI. + location / { + fastcgi_pass 127.0.0.1:26543; + include /etc/nginx/fastcgi_params; + + # our understanding vs nginx's handling of script_name vs + # path_info don't match :) + fastcgi_param PATH_INFO $fastcgi_script_name; + fastcgi_param SCRIPT_NAME ""; + } + } + +Now, nginx instance is configured to serve the MediaGoblin +application. Perform a quick test to ensure that this configuration +works. Restart nginx so it picks up your changes, with a command that +resembles one of the following (as the root user):: + + sudo /etc/init.d/nginx restart + sudo /etc/rc.d/nginx restart + +Now start MediaGoblin. Use the following command sequence as an +example:: + + cd /srv/mediagoblin.example.org/mediagoblin/ + ./lazyserver.sh --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 + +Visit the site you've set up in your browser by visiting +. You should see MediaGoblin! + +.. note:: + + The configuration described above is sufficient for development and + smaller deployments. However, for larger production deployments + with larger processing requirements, see the + ":doc:`production-deployments`" documentation. diff --git a/docs/source/siteadmin/foreword.rst b/docs/source/siteadmin/foreword.rst new file mode 100644 index 00000000..4c425f8d --- /dev/null +++ b/docs/source/siteadmin/foreword.rst @@ -0,0 +1,48 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +======== +Foreword +======== + +About the Site Administrator's Guide +==================================== + +This is the site administrator manual for GNU MediaGoblin. It covers +how to set up and configure MediaGoblin and the kind of information +that someone running MediaGoblin would need to know. + +We have other documentation at: + +* http://mediagoblin.org/join/ for general "join us" information +* http://wiki.mediagoblin.org/ for our contributor/developer-focused wiki + + +Improving the Site Administrator's Guide +======================================== + +There are a few ways---please pick whichever method is convenient for +you! + +1. Write up a bug report in the bug tracker +2. Tell someone on IRC ``#mediagoblin`` on Freenode. +3. Write an email to the devel mailing list. + +Information about the bugtracker, IRC and the mailing list is all on +the `join page`_. + +.. _join page: http://mediagoblin.org/join/ + +Patches are the most helpful, but even feedback on what you think +could be improved and how to improve it is also helpful. + diff --git a/docs/source/siteadmin/help.rst b/docs/source/siteadmin/help.rst new file mode 100644 index 00000000..4b584ac1 --- /dev/null +++ b/docs/source/siteadmin/help.rst @@ -0,0 +1,29 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +================================== + How to Get Help with MediaGoblin +================================== + +There are a couple of ways to get help with problems with MediaGoblin: + +1. ask for help on IRC + +2. ask for help on the devel mailing list + +Details for both IRC and the mailing list are on the `join page`_ of the +website. + +.. _join page: http://mediagoblin.org/join/ + + diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst new file mode 100644 index 00000000..1cf7f30c --- /dev/null +++ b/docs/source/siteadmin/media-types.rst @@ -0,0 +1,76 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +.. _media-types-chapter: + +==================== +Enabling Media Types +==================== + +In the future, there will be all sorts of media types you can enable, +but in the meanwhile there are two additional media type: video and +ascii art. + +First, you should probably read ":doc:`configuration`" to make sure +you know how to modify the mediagoblin config file. + +Video +===== + +To enable video, first install gstreamer and the python-gstreamer +bindings (as well as whatever gstremaer extensions you want, +good/bad/ugly). On Debianoid systems:: + + sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \ + gstreamer0.10-ffmpeg + +Next, modify (and possibly copy over from ``mediagoblin.ini``) your +``mediagoblin_local.ini``. In the ``[mediagoblin]`` section, add +``mediagoblin.media_types.video`` to the ``media_types`` list. + +For example, if your system supported image and video media types, then +the list would look like this:: + + media_types = mediagoblin.media_types.image, mediagoblin.media_types.video + +Now you should be able to submit videos, and mediagoblin should +transcode them. + +.. note:: + + You almost certainly want to separate Celery from the normal + paste process or your users will probably find that their connections + time out as the video transcodes. To set that up, check out the + ":doc:`production-deployments`" section of this manual. + + +Ascii art +========= + +To enable ascii art support, first install the +`chardet `_ +library, which is necessary for creating thumbnails of ascii art:: + + ./bin/easy_install chardet + + +Next, modify (and possibly copy over from ``mediagoblin.ini``) your +``mediagoblin_local.ini``. In the ``[mediagoblin]`` section, add +``mediagoblin.media_types.ascii`` to the ``media_types`` list. + +For example, if your system supported image and ascii art media types, then +the list would look like this:: + + media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii + +Now any .txt file you uploaded will be processed as ascii art! diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst new file mode 100644 index 00000000..41f2970f --- /dev/null +++ b/docs/source/siteadmin/plugins.rst @@ -0,0 +1,137 @@ +========= + Plugins +========= + +GNU MediaGoblin supports plugins that allow you to augment MediaGoblin's +behavior. + +This chapter covers discovering, installing, configuring and removing +plugins. + + +Discovering plugins +=================== + +MediaGoblin comes with core plugins. Core plugins are located in the +``mediagoblin.plugins`` module of the MediaGoblin code. Because they +come with MediaGoblin, you don't have to install them, but you do have +to add them to your config file if you're interested in using them. + +You can also write your own plugins and additionally find plugins +elsewhere on the Internet. Once you find a plugin you like, you need +to first install it, then add it to your configuration. + +.. todo: how do you find plugins on the internet? + + +Installing plugins +================== + +Core plugins +------------ + +MediaGoblin core plugins don't need to be installed because they come +with MediaGoblin. Further, when you upgrade MediaGoblin, you will also +get updates to the core plugins. + + +Other plugins +------------- + +If the plugin is available on the `Python Package Index +`_, then you can install the plugin with pip:: + + pip install + +For example, if we wanted to install the plugin named +"mediagoblin-restrictfive", we would do:: + + pip install mediagoblin-restrictfive + +.. Note:: + + If you're using a virtual environment, make sure to activate the + virtual environment before installing with pip. Otherwise the + plugin may get installed in a different environment than the one + MediaGoblin is installed in. + +Once you've installed the plugin software, you need to tell +MediaGoblin that this is a plugin you want MediaGoblin to use. To do +that, you edit the ``mediagoblin.ini`` file and add the plugin as a +subsection of the plugin section. + +For example, say the "mediagoblin-restrictfive" plugin had the Python +package path ``restrictfive``, then you would add ``restrictfive`` to +the ``plugins`` section as a subsection:: + + [plugins] + + [[restrictfive]] + + +Configuring plugins +=================== + +Configuration for a plugin goes in the subsection for that plugin. Core +plugins are documented in the administration guide. Other plugins +should come with documentation that tells you how to configure them. + +Example 1: Core MediaGoblin plugin + +If you wanted to use the core MediaGoblin flatpages plugin, the module +for that is ``mediagoblin.plugins.flatpages`` and you would add that +to your ``.ini`` file like this:: + + [plugins] + + [[mediagoblin.plugins.flatpages]] + # configuration for flatpages plugin here! + directory = /srv/mediagoblin/flatpages + +Example 2: Plugin that is not a core MediaGoblin plugin + +If you installed a hypothetical restrictfive plugin which is in the +module ``restrictfive``, your ``.ini`` file might look like this (with +comments making the bits clearer):: + + [plugins] + + [[restrictfive]] + # configuration for restrictfive here! + +Check the plugin's documentation for what configuration options are +available. + + +Removing plugins +================ + +To remove a plugin, use ``pip uninstall``. For example:: + + pip uninstall mediagoblin-restrictfive + +.. Note:: + + If you're using a virtual environment, make sure to activate the + virtual environment before uninstalling with pip. Otherwise the + plugin may get installed in a different environment. + + +Upgrading plugins +================= + +Core plugins +------------ + +Core plugins get upgraded automatically when you upgrade MediaGoblin +because they come with MediaGoblin. + + +Other plugins +------------- + +For plugins that you install with pip, you can upgrade them with pip:: + + pip install -U + +The ``-U`` tells pip to upgrade the package. diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst new file mode 100644 index 00000000..1e6631db --- /dev/null +++ b/docs/source/siteadmin/production-deployments.rst @@ -0,0 +1,94 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +========================================= +Considerations for Production Deployments +========================================= + +This document contains a number of suggestions for deploying +MediaGoblin in actual production environments. Consider +":doc:`deploying`" for a basic overview of how to deploy MediaGoblin. + +Deploy with Paste +----------------- + +The instance configured with ``./lazyserver.sh`` is not ideal for a +production MediaGoblin deployment. Ideally, you should be able to use +an "init" or "control" script to launch and restart the MediaGoblin +process. + +Use the following command as the basis for such a script: :: + + CELERY_ALWAYS_EAGER=true \ + /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ + /srv/mediagoblin.example.org/mediagoblin/paste.ini \ + --pid-file=/var/run/mediagoblin.pid \ + --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 + +The above configuration places MediaGoblin in "always eager" mode +with Celery, this means that submissions of content will be processed +synchronously, and the user will advance to the next page only after +processing is complete. If we take Celery out of "always eager mode," +the user will be able to immediately return to the MediaGoblin site +while processing is ongoing. In these cases, use the following command +as the basis for your script: :: + + CELERY_ALWAYS_EAGER=false \ + /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ + /srv/mediagoblin.example.org/mediagoblin/paste.ini \ + --pid-file=/var/run/mediagoblin.pid \ + --server-name=fcgi fcgi_host=127.0.0.1 fcgi_port=26543 + +Separate Celery +--------------- + +While the ``./lazyserer.sh`` configuration provides an efficient way to +start using a MediaGoblin instance, it is not suitable for production +deployments for several reasons: + +In nearly every scenario, work on the Celery queue will need to +balance with the demands of other processes, and cannot proceed +synchronously. This is a particularly relevant problem if you use +MediaGoblin to host video content. Processing with Celery ought to be +operationally separate from the MediaGoblin application itself, this +simplifies management and support better workload distribution. + +Basically, if you're doing anything beyond a trivial workload, such as +image hosting for a small set of users, or have limited media types +such as "ASCII art" or icon sharing, you will need to run ``celeryd`` +as a separate process. + +Build an :ref:`init script ` around the following +command:: + + CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd + +Modify your existing MediaGoblin and application init scripts, if +necessary, to prevent them from starting their own ``celeryd`` +processes. + +.. _init-script: + +Use an Init Script +------------------ + +Look in your system's ``/etc/init.d/`` or ``/etc/rc.d/`` directory for +examples of how to build scripts that will start, stop, and restart +MediaGoblin and Celery. These scripts will vary by +distribution/operating system. In the future, MediaGoblin will provide +example scripts as examples. + +.. TODO insert init script here +.. TODO are additional concerns ? + .. Other Concerns + .. -------------- diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst new file mode 100644 index 00000000..2efded73 --- /dev/null +++ b/docs/source/siteadmin/relnotes.rst @@ -0,0 +1,52 @@ +.. MediaGoblin Documentation + + Written in 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +============= +Release Notes +============= + +This chapter has important information for releases in it. +If you're upgrading from a previous release, please read it +carefully, or at least skim over it. + + +0.3.0 +===== + +This release has one important change. You need to act when +upgrading from a previous version! + +This release changes the database system from MongoDB to +SQL(alchemy). If you want to setup a fresh instance, just +follow the instructions in the deployment chapter. If on +the other hand you want to continue to use one instance, +read on. + +To convert your data from MongoDB to SQL(alchemy), you need +to follow these steps: + +1. Make sure your MongoDB is still running and has your + data, it's needed for the conversion. + +2. Configure the ``sql_engine`` URI in the config to represent + your target database (see: :ref:`deploying-chapter`) + +3. You need an empty database. + +4. Then run the following command:: + + bin/gmg [-cf mediagoblin_config.ini] convert_mongo_to_sql + +5. Start your server and investigate. + +6. That's it. diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst new file mode 100644 index 00000000..7584b688 --- /dev/null +++ b/docs/source/siteadmin/theming.rst @@ -0,0 +1,21 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +.. _theming-chapter: + +===================== + Theming MediaGoblin +===================== + +We haven't implemented the necessary scaffolding to allow for theming +yet. Thus, this chapter is a stub. diff --git a/docs/source/snugglygoblin.png b/docs/source/snugglygoblin.png deleted file mode 100644 index f325ae4b..00000000 Binary files a/docs/source/snugglygoblin.png and /dev/null differ diff --git a/docs/source/theming.rst b/docs/source/theming.rst deleted file mode 100644 index 7584b688..00000000 --- a/docs/source/theming.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - . - -.. _theming-chapter: - -===================== - Theming MediaGoblin -===================== - -We haven't implemented the necessary scaffolding to allow for theming -yet. Thus, this chapter is a stub. -- cgit v1.2.3 From 4f94f29da998a219e8a1a8436c5d3e6b3f6852d3 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 23 May 2012 20:35:53 -0400 Subject: Add build date to docs Makes it easier to spot when the docs aren't rebuilding correctly. --- docs/source/index.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index dc8bacc7..3b13b1bc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -57,3 +57,4 @@ Indices and tables .. * :ref:`modindex` +This guide was built on |today|. -- cgit v1.2.3 From 469f10e4a7d3cfdd6cc937344dc47b89608198fa Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 23 May 2012 21:16:18 -0400 Subject: Add plugin writer's quickstart guide --- docs/source/index.rst | 1 + docs/source/pluginwriter/quickstart.rst | 189 ++++++++++++++++++++++++++++++++ 2 files changed, 190 insertions(+) create mode 100644 docs/source/pluginwriter/quickstart.rst (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index 3b13b1bc..5b8d5c85 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -47,6 +47,7 @@ This guide covers writing new GNU MediaGoblin plugins. :maxdepth: 1 pluginwriter/foreward + pluginwriter/quickstart Indices and tables diff --git a/docs/source/pluginwriter/quickstart.rst b/docs/source/pluginwriter/quickstart.rst new file mode 100644 index 00000000..73531381 --- /dev/null +++ b/docs/source/pluginwriter/quickstart.rst @@ -0,0 +1,189 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + + +=========== +Quick Start +=========== + +This is a quick start. It's not comprehensive, but it walks through +writing a basic plugin called "sampleplugin" which logs "I've been +started!" when ``setup_plugin()`` has been called. + +.. todo: Rewrite this to be a useful plugin + + +Step 1: Files and directories +============================= + +GNU MediaGoblin plugins are Python projects at heart. As such, you should +use a standard Python project directory tree:: + + sampleplugin/ + |- README + |- LICENSE + |- setup.py + |- sampleplugin/ + |- __init__.py + + +The outer ``sampleplugin`` directory holds all the project files. + +The ``README`` should cover what your plugin does, how to install it, +how to configure it, and all the sorts of things a README should +cover. + +The ``LICENSE`` should have the license under which you're +distributing your plugin. + +The inner ``sampleplugin`` directory is the Python package that holds +your plugin's code. + +The ``__init__.py`` denotes that this is a Python package. It also +holds the plugin code. + + +Step 2: README +============== + +Here's a rough ``README``. Generally, you want more information +because this is the file that most people open when they want to learn +more about your project. + +:: + + README + ====== + + This is a sample plugin. It logs a line when ``setup__plugin()`` is + run. + + +Step 3: LICENSE +=============== + +GNU MediaGoblin plugins must be licensed under the AGPLv3 or later. So +the LICENSE file should be the AGPLv3 text which you can find at +``_ + + +Step 4: setup.py +================ + +This file is used for packaging and distributing your plugin. + +We'll use a basic one:: + + from setuptools import setup, find_packages + + setup( + name='sampleplugin', + version='1.0', + packages=find_packages(), + include_package_data=True, + install_requires=[], + license='AGPLv3', + ) + + +See ``_ +for more details. + + +Step 5: the code +================ + +The code for ``__init__.py`` looks like this: + +.. code-block:: python + :linenos: + :emphasize-lines: 8,19 + + import logging + from mediagoblin.tools.pluginapi import Plugin, get_config + + + _log = logging.getLogger(__name__) + + + class SamplePlugin(Plugin): + """ + This is a sample plugin class. It automatically registers itself + with MediaGoblin when this module is imported. + + The setup_plugin method prints configuration for this plugin if + there is any. + """ + def __init__(self): + pass + + def setup_plugin(self): + _log.info("I've been started!") + config = get_config('sampleplugin') + if config: + _log.info('%r' % config) + else: + _log.info('There is no configuration set.') + + +Line 8 defines a class called ``SamplePlugin`` that subclasses +``Plugin`` from ``mediagoblin.tools.pluginapi``. When the class is +defined, it gets registered with MediaGoblin and MediaGoblin will then +call ``setup_plugin`` on it. + +Line 19 defines ``setup_plugin``. This gets called when MediaGoblin +starts up after it's registered all the plugins. This is where you can +do any initialization for your plugin. + + +Step 6: Installation and configuration +====================================== + +To install the plugin for development, you need to make sure it's +available to the Python interpreter that's running MediaGoblin. + +There are a couple of ways to do this, but we're going to pick the +easy one. + +Use ``python`` from your MediaGoblin virtual environment and do:: + + python setup.py develop + +Any changes you make to your plugin will be available in your +MediaGoblin virtual environment. + +Then adjust your ``mediagoblin.ini`` file to load the plugin:: + + [plugins] + + [[sampleplugin]] + + +Step 7: That's it! +================== + +When you launch MediaGoblin, it'll load the plugin and you'll see +evidence of that in the log file. + +That's it for the quick start! + + +Where to go from here +===================== + +See the documentation on the plugin API for code samples and other +things you can use when building your plugin. + +See `Hitchhiker's Guide to Packaging +`_ for more information on +packaging your plugin. -- cgit v1.2.3 From 84336a46b1b95aab9733a9ff0ac3c03303a326c5 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Mon, 28 May 2012 01:08:38 +0200 Subject: Added links to community-provied init scripts --- docs/source/siteadmin/production-deployments.rst | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst index 1e6631db..356fab7f 100644 --- a/docs/source/siteadmin/production-deployments.rst +++ b/docs/source/siteadmin/production-deployments.rst @@ -85,8 +85,22 @@ Use an Init Script Look in your system's ``/etc/init.d/`` or ``/etc/rc.d/`` directory for examples of how to build scripts that will start, stop, and restart MediaGoblin and Celery. These scripts will vary by -distribution/operating system. In the future, MediaGoblin will provide -example scripts as examples. +distribution/operating system. + +These are scripts provided by the MediaGoblin community: + +Debian + * `GNU MediaGoblin init scripts + `_ + by `Joar Wandborg `_ + +Arch Linux + * `MediaGoblin - ArchLinux rc.d scripts + `_ + by `Jeremy Pope `_ + * `Mediagoblin init script on Archlinux + `_ + by `Chimo `_ .. TODO insert init script here .. TODO are additional concerns ? -- cgit v1.2.3 From 0e60e7e81b58f2ef8ca4bd571bb9544e41e573c8 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sat, 2 Jun 2012 22:03:03 -0400 Subject: Add link to wiki on front page; fix about Adds a summary and a link to the wiki for contributors to the front page. The "what is mediagoblin" section in the about chapter talkd about what it was, but it was buried--this slightly unburies it. --- docs/source/index.rst | 9 +++++++++ docs/source/siteadmin/about.rst | 9 +++++---- 2 files changed, 14 insertions(+), 4 deletions(-) (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index 5b8d5c85..569eda14 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,6 +16,15 @@ Welcome to GNU MediaGoblin's documentation! =========================================== +GNU MediaGoblin is a platform for sharing photos, video and other media +in an environment that respects our freedom and independence. + +This is a Free Software project. It is built by contributors for all +to use and enjoy. If you're intrested in contributing, see `the wiki +`_ which has pages that talk about the +ways someone can contribute. + + Part 1: Site Administrator's Guide ================================== diff --git a/docs/source/siteadmin/about.rst b/docs/source/siteadmin/about.rst index 95647abb..f9602397 100644 --- a/docs/source/siteadmin/about.rst +++ b/docs/source/siteadmin/about.rst @@ -36,10 +36,11 @@ freedom look like on the participatory web?" Their answer, the Identi.ca and Libre.fm address the need for micro-blogging and music sharing services and software that respect users' freedom and -autonomy. GNU MediaGoblin emerges from this milieu to create a -platform for us to share photos in an environment that respects our -freedom and independence. In the future MediaGoblin will include -support other media, like video, and provide tools to facilitate +autonomy. + +GNU MediaGoblin emerges from this milieu to create a platform for us to share +photos, video and other media in an environment that respects our freedom and +independence. In the future MediaGoblin will provide tools to facilitate collaboration on media projects. -- cgit v1.2.3 From 6f8714fea4b4ce112fbf6dda6f71122e61cfdcf7 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 1 Jul 2012 10:34:29 -0500 Subject: Changing mediagoblin theme font files over to be symlinks to extlib --- docs/source/themes/mg/static/fonts/Lato-Bold.ttf | Bin 93224 -> 43 bytes .../themes/mg/static/fonts/Lato-BoldItalic.ttf | Bin 81936 -> 49 bytes docs/source/themes/mg/static/fonts/Lato-Italic.ttf | Bin 83680 -> 45 bytes .../source/themes/mg/static/fonts/Lato-Regular.ttf | Bin 96044 -> 46 bytes docs/source/themes/mg/static/fonts/OFL_1.1.txt | 98 +-------------------- 5 files changed, 1 insertion(+), 97 deletions(-) mode change 100644 => 120000 docs/source/themes/mg/static/fonts/Lato-Bold.ttf mode change 100644 => 120000 docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf mode change 100644 => 120000 docs/source/themes/mg/static/fonts/Lato-Italic.ttf mode change 100644 => 120000 docs/source/themes/mg/static/fonts/Lato-Regular.ttf mode change 100644 => 120000 docs/source/themes/mg/static/fonts/OFL_1.1.txt (limited to 'docs/source') diff --git a/docs/source/themes/mg/static/fonts/Lato-Bold.ttf b/docs/source/themes/mg/static/fonts/Lato-Bold.ttf deleted file mode 100644 index bc3529fc..00000000 Binary files a/docs/source/themes/mg/static/fonts/Lato-Bold.ttf and /dev/null differ diff --git a/docs/source/themes/mg/static/fonts/Lato-Bold.ttf b/docs/source/themes/mg/static/fonts/Lato-Bold.ttf new file mode 120000 index 00000000..4e08d84d --- /dev/null +++ b/docs/source/themes/mg/static/fonts/Lato-Bold.ttf @@ -0,0 +1 @@ +../../../../../../extlib/lato/Lato-Bold.ttf \ No newline at end of file diff --git a/docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf b/docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf deleted file mode 100644 index 2cf5ae0d..00000000 Binary files a/docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf and /dev/null differ diff --git a/docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf b/docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf new file mode 120000 index 00000000..0b99eef8 --- /dev/null +++ b/docs/source/themes/mg/static/fonts/Lato-BoldItalic.ttf @@ -0,0 +1 @@ +../../../../../../extlib/lato/Lato-BoldItalic.ttf \ No newline at end of file diff --git a/docs/source/themes/mg/static/fonts/Lato-Italic.ttf b/docs/source/themes/mg/static/fonts/Lato-Italic.ttf deleted file mode 100644 index 11ca3eb6..00000000 Binary files a/docs/source/themes/mg/static/fonts/Lato-Italic.ttf and /dev/null differ diff --git a/docs/source/themes/mg/static/fonts/Lato-Italic.ttf b/docs/source/themes/mg/static/fonts/Lato-Italic.ttf new file mode 120000 index 00000000..2dccfc82 --- /dev/null +++ b/docs/source/themes/mg/static/fonts/Lato-Italic.ttf @@ -0,0 +1 @@ +../../../../../../extlib/lato/Lato-Italic.ttf \ No newline at end of file diff --git a/docs/source/themes/mg/static/fonts/Lato-Regular.ttf b/docs/source/themes/mg/static/fonts/Lato-Regular.ttf deleted file mode 100644 index 26ce1002..00000000 Binary files a/docs/source/themes/mg/static/fonts/Lato-Regular.ttf and /dev/null differ diff --git a/docs/source/themes/mg/static/fonts/Lato-Regular.ttf b/docs/source/themes/mg/static/fonts/Lato-Regular.ttf new file mode 120000 index 00000000..7b1bb468 --- /dev/null +++ b/docs/source/themes/mg/static/fonts/Lato-Regular.ttf @@ -0,0 +1 @@ +../../../../../../extlib/lato/Lato-Regular.ttf \ No newline at end of file diff --git a/docs/source/themes/mg/static/fonts/OFL_1.1.txt b/docs/source/themes/mg/static/fonts/OFL_1.1.txt deleted file mode 100644 index f1a20ac1..00000000 --- a/docs/source/themes/mg/static/fonts/OFL_1.1.txt +++ /dev/null @@ -1,97 +0,0 @@ -Copyright (c) , (), -with Reserved Font Name . -Copyright (c) , (), -with Reserved Font Name . -Copyright (c) , (). - -This Font Software is licensed under the SIL Open Font License, Version 1.1. -This license is copied below, and is also available with a FAQ at: -http://scripts.sil.org/OFL - - ------------------------------------------------------------ -SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 ------------------------------------------------------------ - -PREAMBLE -The goals of the Open Font License (OFL) are to stimulate worldwide -development of collaborative font projects, to support the font creation -efforts of academic and linguistic communities, and to provide a free and -open framework in which fonts may be shared and improved in partnership -with others. - -The OFL allows the licensed fonts to be used, studied, modified and -redistributed freely as long as they are not sold by themselves. The -fonts, including any derivative works, can be bundled, embedded, -redistributed and/or sold with any software provided that any reserved -names are not used by derivative works. The fonts and derivatives, -however, cannot be released under any other type of license. The -requirement for fonts to remain under this license does not apply -to any document created using the fonts or their derivatives. - -DEFINITIONS -"Font Software" refers to the set of files released by the Copyright -Holder(s) under this license and clearly marked as such. This may -include source files, build scripts and documentation. - -"Reserved Font Name" refers to any names specified as such after the -copyright statement(s). - -"Original Version" refers to the collection of Font Software components as -distributed by the Copyright Holder(s). - -"Modified Version" refers to any derivative made by adding to, deleting, -or substituting -- in part or in whole -- any of the components of the -Original Version, by changing formats or by porting the Font Software to a -new environment. - -"Author" refers to any designer, engineer, programmer, technical -writer or other person who contributed to the Font Software. - -PERMISSION & CONDITIONS -Permission is hereby granted, free of charge, to any person obtaining -a copy of the Font Software, to use, study, copy, merge, embed, modify, -redistribute, and sell modified and unmodified copies of the Font -Software, subject to the following conditions: - -1) Neither the Font Software nor any of its individual components, -in Original or Modified Versions, may be sold by itself. - -2) Original or Modified Versions of the Font Software may be bundled, -redistributed and/or sold with any software, provided that each copy -contains the above copyright notice and this license. These can be -included either as stand-alone text files, human-readable headers or -in the appropriate machine-readable metadata fields within text or -binary files as long as those fields can be easily viewed by the user. - -3) No Modified Version of the Font Software may use the Reserved Font -Name(s) unless explicit written permission is granted by the corresponding -Copyright Holder. This restriction only applies to the primary font name as -presented to the users. - -4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font -Software shall not be used to promote, endorse or advertise any -Modified Version, except to acknowledge the contribution(s) of the -Copyright Holder(s) and the Author(s) or with their explicit written -permission. - -5) The Font Software, modified or unmodified, in part or in whole, -must be distributed entirely under this license, and must not be -distributed under any other license. The requirement for fonts to -remain under this license does not apply to any document created -using the Font Software. - -TERMINATION -This license becomes null and void if any of the above conditions are -not met. - -DISCLAIMER -THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT -OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE -COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL -DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM -OTHER DEALINGS IN THE FONT SOFTWARE. diff --git a/docs/source/themes/mg/static/fonts/OFL_1.1.txt b/docs/source/themes/mg/static/fonts/OFL_1.1.txt new file mode 120000 index 00000000..e71d0721 --- /dev/null +++ b/docs/source/themes/mg/static/fonts/OFL_1.1.txt @@ -0,0 +1 @@ +../../../../../../extlib/lato/OFL_1.1.txt \ No newline at end of file -- cgit v1.2.3 From d34757dc830903fc55898ca7ea923f7a2ea6e646 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Fri, 6 Jul 2012 22:51:49 +0200 Subject: Updated the media types documentation, added steps for audio - Added chapter about media type negotiation. - Added instructions on how to install dependencies for the audio media type. - Moved part about how to enable media types in your config to a single place at the top of the document named "Enable Media Types". - Renamed the "Enable Media Types" page to "Media Types". --- docs/source/siteadmin/media-types.rst | 73 +++++++++++++++++++++++++++++------ 1 file changed, 62 insertions(+), 11 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 1cf7f30c..d062da95 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -14,16 +14,49 @@ .. _media-types-chapter: ==================== -Enabling Media Types +Media Types ==================== In the future, there will be all sorts of media types you can enable, -but in the meanwhile there are two additional media type: video and -ascii art. +but in the meanwhile there are three additional media types: video, audio +and ascii art. First, you should probably read ":doc:`configuration`" to make sure you know how to modify the mediagoblin config file. + +Enabling Media Types +==================== + +Media types are enabled in your mediagoblin configuration file, typically it is +created by copying ``mediagoblin.ini`` to ``mediagoblin_local.ini`` and then +applying your changes to ``mediagoblin_local.ini``. If you don't already have a +``mediagoblin_local.ini``, create one in the way described. + +Most media types have additional dependencies that you will have to install. +You will find descriptions on how to satisfy the requirements of each media type +on this page. + +To enable a media type, edit the ``media_types`` list in your +``mediagoblin_local.ini``. For example, if your system supported image and +video media types, then the list would look like this:: + + media_types = mediagoblin.media_types.image, mediagoblin.media_types.video + +How does MediaGoblin decide which media type to use for a file? +=============================================================== + +MediaGoblin has two methods for finding the right media type for an uploaded +file. One is based on the file extension of the uploaded file; every media type +maintains a list of supported file extensions. The second is based on a sniffing +handler, where every media type may inspect the uploaded file and tell if it +will accept it. + +The file-extension-based approach is used before the sniffing-based approach, +if the file-extension-based approach finds a match, the sniffing-based approach +will be skipped as it uses far more processing power. + + Video ===== @@ -34,14 +67,6 @@ good/bad/ugly). On Debianoid systems:: sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \ gstreamer0.10-ffmpeg -Next, modify (and possibly copy over from ``mediagoblin.ini``) your -``mediagoblin_local.ini``. In the ``[mediagoblin]`` section, add -``mediagoblin.media_types.video`` to the ``media_types`` list. - -For example, if your system supported image and video media types, then -the list would look like this:: - - media_types = mediagoblin.media_types.image, mediagoblin.media_types.video Now you should be able to submit videos, and mediagoblin should transcode them. @@ -54,6 +79,32 @@ transcode them. ":doc:`production-deployments`" section of this manual. +Audio +===== + +To enable audio, install the gstreamer and python-gstreamer bindings (as well +as whatever gstreamer plugins you want, good/bad/ugly), scipy and numpy are +also needed for the audio spectrograms. +To install these on Debianoid systems, run:: + + sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \ + gstreamer0.10-ffmpeg python-numpy python-scipy + +The ``scikits.audiolab`` package you will install in the next step depends on the +``libsndfile1-dev`` package, so we should install it. +On Debianoid systems, run:: + + sudo apt-get install libsndfile1-dev + +Then install ``scikits.audiolab`` for the spectrograms:: + + ./bin/pip install scikits.audiolab + +Add ``mediagoblin.media_types.audio`` to the ``media_types`` list in your +``mediagoblin_local.ini`` and restart MediaGoblin. You should now be able to +upload and listen to audio files! + + Ascii art ========= -- cgit v1.2.3 From e6aaaa96193b20d805c82214debd5a2cd8855efd Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sat, 14 Jul 2012 15:54:14 -0500 Subject: Fleshing out theming documentation; wrote out "structure of things" section --- docs/source/siteadmin/theming.rst | 94 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 92 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index 7584b688..27f39e97 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -17,5 +17,95 @@ Theming MediaGoblin ===================== -We haven't implemented the necessary scaffolding to allow for theming -yet. Thus, this chapter is a stub. +We try to provide a nice theme for MediaGoblin by default. But of +course, you might want something different! Maybe you want something +more light and colorful, or maybe you want something specifically +tailored to your organization. Have no fear, MediaGoblin has theming +support! This guide should walk you through installing and making themes. + + +Making a theme +-------------- + +The structure of things +======================= + +Okay, so a theme layout is pretty simple. Let's assume we're making a +theme for an instance about hedgehogs! We'll call this the +"hedgehogified" theme. + + hedgehogified/ + |- theme.cfg # configuration file for this theme + |- templates/ # override templates + | '- mediagoblin/ + | |- base.html # overriding mediagoblin/base.html + | '- root.html # overriding mediagoblin/root.html + '- assets/ + | '- images/ + | | |- im_a_hedgehog.png # hedgehog-containing image used by theme + | | '- custom_logo.png # your theme's custom logo + | '- css/ + | '- hedgehog.css # your site's hedgehog-specific css + |- README.txt # Optionally, a readme file (not required) + |- AGPLv3.txt # AGPL license file for your theme. (good practice) + '- CC0.txt # CC0 1.0 legalcode for the assets [if appropriate!] + +The top level directory of your theme should be the symbolic name for +your theme. This is the name that users will use to refer to activate +your theme. + +It's important to note that templates based on MediaGoblin's code +should be released as AGPLv3 (or later), like MediaGoblin's code +itself. However, all the rest of your assets are up to you. In this +case, we are waiving our copyright for images and CSS into the public +domain via CC0 (as MediaGoblin does) but do what's appropriate to you. + +The config file +~~~~~~~~~~~~~~~ + +Only a few things need to go in here. + + [theme] + name = hedgehogified + description = For hedgehog lovers ONLY + licensing = AGPLv3 or later templates; assets (images/css) waived under CC0 1.0 + + +Templates +~~~~~~~~~ + +Templates + +Licensing file(s) +~~~~~~~~~~~~~~~~~ + + + + +A README.txt file +~~~~~~~~~~~~~~~~~ + +A readme file is not strictly required, but probably a good idea. + + +Referring to custom assets in your themes +========================================= + + + + +Installing a theme +------------------ + +Installing a theme in MediaGoblin is fairly easy! Assuming you +already have a theme package, just do this: + + $ ./bin/gmg theme install --fullsetup goblincities.tar.gz + +This installs, archives, and + + +Making a themes +--------------- + + -- cgit v1.2.3 From 04b24107fbe197a8bd278b908651cea14911dff4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sat, 14 Jul 2012 20:22:25 -0500 Subject: Mostly good theming documentation! --- docs/source/siteadmin/theming.rst | 173 +++++++++++++++++++++++++++++++++----- 1 file changed, 150 insertions(+), 23 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index 27f39e97..63beaf3c 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -24,16 +24,92 @@ tailored to your organization. Have no fear, MediaGoblin has theming support! This guide should walk you through installing and making themes. +Installing a theme +------------------ + +Installing the archive +====================== + +Say you have a theme archive such as goblincities.tar.gz. You want to +install this theme! Don't worry, it's fairly painless. + +Simply cd to the "install directory" for themes (by default, +./user_dev/themes/ relative to the mediagoblin install directory... to +configure these things, see the next section), move the archive there, +and decompress. + + tar xvfz goblincities.tar.gz + +Next, open up your mediagoblin configuration file (probably +mediagoblin_local.ini) and set the theme name: + + [mediagoblin] + # ... + theme = goblincities + +Finally, "link the assets" so that they can be served by your web +server. + + ./bin/gmg theme assetlink + +Note, if you ever change the current theme in your config file, you +should re-run the above command! + +(In the near future this should be even easier ;)) + +.. In the future, this might look more like: +.. Installing a theme in MediaGoblin is fairly easy! Assuming you +.. already have a theme package, just do this: + +.. $ ./bin/gmg theme install --fullsetup goblincities.tar.gz + +.. This would install the theme, set it as current, and symlink its +.. assets. + + +Set up your webserver to serve theme assets +=========================================== + +Section to be written, ask on #mediagoblin in irc.freenode.net in the +meanwhile ;) + +Configuring where things go +=========================== + +By default, MediaGoblin's install directory for themes is +./user_dev/themes/ (relative to the MediaGoblin checkout or base +config file.) However, you can change this location easily. In your +mediagoblin config file, under the section [mediagoblin] set the +following parameter: + + [mediagoblin] + # ... other parameters go here ... + theme_install_dir = /path/to/themes/ + +Other variables you may consider setting: + + - theme_web_path: when theme-specific assets are specified, this is + where MediaGoblin will set the urls. By default this is + "/theme_static/" so in the case that your theme was trying to + access its file "images/shiny_button.png" MediaGoblin would link + to /theme_static/images/shiny_button.png + - theme_linked_assets_dir: Your web server needs to serve the theme + files out of some directory, and MediaGoblin will symlink the + current theme's assets here. (See "Linking assets" in the theme + install section) + + Making a theme -------------- -The structure of things -======================= - Okay, so a theme layout is pretty simple. Let's assume we're making a theme for an instance about hedgehogs! We'll call this the "hedgehogified" theme. +Change to where your theme_install_dir is set to (by default, +./user_dev/themes/ ... make those directories if necessary and +otherwise adjust if necessary) + hedgehogified/ |- theme.cfg # configuration file for this theme |- templates/ # override templates @@ -48,7 +124,7 @@ theme for an instance about hedgehogs! We'll call this the | '- hedgehog.css # your site's hedgehog-specific css |- README.txt # Optionally, a readme file (not required) |- AGPLv3.txt # AGPL license file for your theme. (good practice) - '- CC0.txt # CC0 1.0 legalcode for the assets [if appropriate!] + '- CC0_1.0.txt # CC0 1.0 legalcode for the assets [if appropriate!] The top level directory of your theme should be the symbolic name for your theme. This is the name that users will use to refer to activate @@ -61,51 +137,102 @@ case, we are waiving our copyright for images and CSS into the public domain via CC0 (as MediaGoblin does) but do what's appropriate to you. The config file -~~~~~~~~~~~~~~~ +=============== +The config file is not presently strictly required, though it is nice to have. Only a few things need to go in here. [theme] - name = hedgehogified + name = Hedgehog-ification description = For hedgehog lovers ONLY licensing = AGPLv3 or later templates; assets (images/css) waived under CC0 1.0 +The name and description fields here are to give users an idea of what +your theme is about. For the moment, we don't have any listing +directories or admin interface, so this probably isn't useful, but +feel free to set it in anticipation of a more glorious future. + +Licensing field is likewise a textual description of the stuff here; +it's recommended that you preserve the "AGPLv3 or later templates" and +specify whatever is appropriate to your assets. -Templates -~~~~~~~~~ Templates +========= -Licensing file(s) -~~~~~~~~~~~~~~~~~ +Your template directory is where you can put any override and custom +templates for MediaGoblin. +These follow the general MediaGoblin theming layout, which means that +the MediaGoblin core templates are all kept under the ./mediagoblin/ +prefix directory. +You can copy files right out of MediaGoblin core and modify them in +this matter if you wish. +To fit with best licensing form, you should either preserve the +MediaGoblin copyright header borrowing from a MediaGoblin template, or +you may include one like the following if a new file: -A README.txt file -~~~~~~~~~~~~~~~~~ + {# + # [YOUR THEME], a MediaGoblin theme + # Copyright (C) [YEAR] [YOUR NAME] + # + # This program is free software: you can redistribute it and/or modify + # it under the terms of the GNU Affero General Public License as published by + # the Free Software Foundation, either version 3 of the License, or + # (at your option) any later version. + # + # This program is distributed in the hope that it will be useful, + # but WITHOUT ANY WARRANTY; without even the implied warranty of + # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + # GNU Affero General Public License for more details. + # + # You should have received a copy of the GNU Affero General Public License + # along with this program. If not, see . + #} -A readme file is not strictly required, but probably a good idea. +Assets +======= -Referring to custom assets in your themes -========================================= +Put any files, such as images, CSS, etc, that are specific to your +theme in here. +You can reference these in your templates like so: + +This will tell MediaGoblin to reference this image from the current theme. -Installing a theme ------------------- -Installing a theme in MediaGoblin is fairly easy! Assuming you -already have a theme package, just do this: +Licensing file(s) +================= + +You should include AGPLv3.txt with your theme as this is required for +the assets. You can copy this from mediagoblin/licenses/ + +In the above example, we also use CC0 to waive our copyrights to +images and css, so we also included CC0_1.0.txt + + +A README.txt file +================= + +A readme file is not strictly required, but probably a good idea. You +can put whatever in here, but restating the license choice clearly is +probably a good idea. + - $ ./bin/gmg theme install --fullsetup goblincities.tar.gz +Packaging it up! +================ -This installs, archives, and +Packaging a theme is really easy. It's just a matter of making an archive! +Change to the installed themes directory and run the following: -Making a themes ---------------- + tar cvfz yourtheme.tar.gz yourtheme +Where "yourtheme" is replaced with your theme name. +That's it! -- cgit v1.2.3 From 62157a898f60fab7c82eb76b2969354f9f02390d Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sat, 14 Jul 2012 22:58:42 -0500 Subject: Added a section describing how to do theming via simple CSS stuff! --- docs/source/siteadmin/theming.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index 63beaf3c..086838bc 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -224,6 +224,30 @@ can put whatever in here, but restating the license choice clearly is probably a good idea. +Simple theming by adding CSS +============================ + +Many themes won't require anything other than the ability to override +some of MediaGoblin's core css. Thankfully, doing so is easy if you +combine the above steps! + +In your theme, do the following (make sure you make the necessary +directories and cd to your theme's directory first): + + $ cp /path/to/mediagoblin/mediagoblin/templates/mediagoblin/extra_head.html templates/mediagoblin/ + +Great, now open that file and add something like this at the end: + + + +You can name the css file whatever you like. Now make the directory +for assets/css/ and add the file assets/css/theme.css + +You can now put custom CSS files in here and any CSS you add will +override default MediaGoblin CSS. + + Packaging it up! ================ -- cgit v1.2.3 From 4bd65f69c710268404e1b1fdaac68db069558584 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Sun, 10 Jun 2012 14:51:13 -0400 Subject: Finish flatpagesplugin; add plugin docs --- docs/source/index.rst | 12 +++++++++++- docs/source/plugindocs/flatpagesfile.rst | 1 + docs/source/plugindocs/sampleplugin.rst | 1 + 3 files changed, 13 insertions(+), 1 deletion(-) create mode 100644 docs/source/plugindocs/flatpagesfile.rst create mode 100644 docs/source/plugindocs/sampleplugin.rst (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index 569eda14..fa637e95 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -47,7 +47,17 @@ MediaGoblin website. It is written for site administrators. siteadmin/codebase -Part 2: Plugin Writer's Guide +Part 2: Core plugin documentation +================================= + +.. toctree:: + :maxdepth: 1 + + plugindocs/flatpagesfile + plugindocs/sampleplugin + + +Part 3: Plugin Writer's Guide ============================= This guide covers writing new GNU MediaGoblin plugins. diff --git a/docs/source/plugindocs/flatpagesfile.rst b/docs/source/plugindocs/flatpagesfile.rst new file mode 100644 index 00000000..68965fda --- /dev/null +++ b/docs/source/plugindocs/flatpagesfile.rst @@ -0,0 +1 @@ +.. include:: ../../../mediagoblin/plugins/flatpagesfile/README.rst diff --git a/docs/source/plugindocs/sampleplugin.rst b/docs/source/plugindocs/sampleplugin.rst new file mode 100644 index 00000000..aa04e4e9 --- /dev/null +++ b/docs/source/plugindocs/sampleplugin.rst @@ -0,0 +1 @@ +.. include:: ../../../mediagoblin/plugins/sampleplugin/README.rst -- cgit v1.2.3 From 8464bcc3e86e223db0739101c0b5d914eea225af Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 16 Jul 2012 17:06:57 -0400 Subject: Fix themeing docs This fixes a bunch of formatting issues in the themeing docs and makes them easier to read. --- docs/source/siteadmin/theming.rst | 151 ++++++++++++++++++++------------------ 1 file changed, 78 insertions(+), 73 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index 086838bc..74bc80dc 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -25,32 +25,32 @@ support! This guide should walk you through installing and making themes. Installing a theme ------------------- +================== Installing the archive -====================== +---------------------- Say you have a theme archive such as goblincities.tar.gz. You want to install this theme! Don't worry, it's fairly painless. Simply cd to the "install directory" for themes (by default, -./user_dev/themes/ relative to the mediagoblin install directory... to +``./user_dev/themes/`` relative to the mediagoblin install directory... to configure these things, see the next section), move the archive there, -and decompress. +and decompress:: - tar xvfz goblincities.tar.gz + $ tar xvfz goblincities.tar.gz Next, open up your mediagoblin configuration file (probably -mediagoblin_local.ini) and set the theme name: +``mediagoblin_local.ini``) and set the theme name:: - [mediagoblin] - # ... - theme = goblincities + [mediagoblin] + # ... + theme = goblincities Finally, "link the assets" so that they can be served by your web -server. +server:: - ./bin/gmg theme assetlink + $ ./bin/gmg theme assetlink Note, if you ever change the current theme in your config file, you should re-run the above command! @@ -59,56 +59,59 @@ should re-run the above command! .. In the future, this might look more like: .. Installing a theme in MediaGoblin is fairly easy! Assuming you -.. already have a theme package, just do this: - -.. $ ./bin/gmg theme install --fullsetup goblincities.tar.gz - +.. already have a theme package, just do this:: +.. +.. $ ./bin/gmg theme install --fullsetup goblincities.tar.gz +.. .. This would install the theme, set it as current, and symlink its .. assets. Set up your webserver to serve theme assets -=========================================== +------------------------------------------- Section to be written, ask on #mediagoblin in irc.freenode.net in the meanwhile ;) + Configuring where things go -=========================== +--------------------------- By default, MediaGoblin's install directory for themes is ./user_dev/themes/ (relative to the MediaGoblin checkout or base config file.) However, you can change this location easily. In your mediagoblin config file, under the section [mediagoblin] set the -following parameter: +following parameter:: - [mediagoblin] - # ... other parameters go here ... - theme_install_dir = /path/to/themes/ + [mediagoblin] + # ... other parameters go here ... + theme_install_dir = /path/to/themes/ Other variables you may consider setting: - - theme_web_path: when theme-specific assets are specified, this is - where MediaGoblin will set the urls. By default this is - "/theme_static/" so in the case that your theme was trying to - access its file "images/shiny_button.png" MediaGoblin would link - to /theme_static/images/shiny_button.png - - theme_linked_assets_dir: Your web server needs to serve the theme - files out of some directory, and MediaGoblin will symlink the - current theme's assets here. (See "Linking assets" in the theme - install section) +`theme_web_path` + When theme-specific assets are specified, this is where MediaGoblin + will set the urls. By default this is ``"/theme_static/"`` so in + the case that your theme was trying to access its file + ``"images/shiny_button.png"`` MediaGoblin would link + to ``/theme_static/images/shiny_button.png``. + +`theme_linked_assets_dir` + Your web server needs to serve the theme files out of some directory, + and MediaGoblin will symlink the current theme's assets here. (See + "Linking assets" in the theme install section) Making a theme --------------- +============== Okay, so a theme layout is pretty simple. Let's assume we're making a theme for an instance about hedgehogs! We'll call this the "hedgehogified" theme. Change to where your theme_install_dir is set to (by default, -./user_dev/themes/ ... make those directories if necessary and -otherwise adjust if necessary) +``./user_dev/themes/`` ... make those directories if necessary and +otherwise adjust if necessary):: hedgehogified/ |- theme.cfg # configuration file for this theme @@ -126,6 +129,7 @@ otherwise adjust if necessary) |- AGPLv3.txt # AGPL license file for your theme. (good practice) '- CC0_1.0.txt # CC0 1.0 legalcode for the assets [if appropriate!] + The top level directory of your theme should be the symbolic name for your theme. This is the name that users will use to refer to activate your theme. @@ -136,16 +140,17 @@ itself. However, all the rest of your assets are up to you. In this case, we are waiving our copyright for images and CSS into the public domain via CC0 (as MediaGoblin does) but do what's appropriate to you. + The config file =============== The config file is not presently strictly required, though it is nice to have. -Only a few things need to go in here. +Only a few things need to go in here:: - [theme] - name = Hedgehog-ification - description = For hedgehog lovers ONLY - licensing = AGPLv3 or later templates; assets (images/css) waived under CC0 1.0 + [theme] + name = Hedgehog-ification + description = For hedgehog lovers ONLY + licensing = AGPLv3 or later templates; assets (images/css) waived under CC0 1.0 The name and description fields here are to give users an idea of what your theme is about. For the moment, we don't have any listing @@ -158,13 +163,13 @@ specify whatever is appropriate to your assets. Templates -========= +--------- Your template directory is where you can put any override and custom templates for MediaGoblin. These follow the general MediaGoblin theming layout, which means that -the MediaGoblin core templates are all kept under the ./mediagoblin/ +the MediaGoblin core templates are all kept under the ``./mediagoblin/`` prefix directory. You can copy files right out of MediaGoblin core and modify them in @@ -172,34 +177,34 @@ this matter if you wish. To fit with best licensing form, you should either preserve the MediaGoblin copyright header borrowing from a MediaGoblin template, or -you may include one like the following if a new file: - - {# - # [YOUR THEME], a MediaGoblin theme - # Copyright (C) [YEAR] [YOUR NAME] - # - # This program is free software: you can redistribute it and/or modify - # it under the terms of the GNU Affero General Public License as published by - # the Free Software Foundation, either version 3 of the License, or - # (at your option) any later version. - # - # This program is distributed in the hope that it will be useful, - # but WITHOUT ANY WARRANTY; without even the implied warranty of - # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - # GNU Affero General Public License for more details. - # - # You should have received a copy of the GNU Affero General Public License - # along with this program. If not, see . - #} +you may include one like the following if a new file:: + + {# + # [YOUR THEME], a MediaGoblin theme + # Copyright (C) [YEAR] [YOUR NAME] + # + # This program is free software: you can redistribute it and/or modify + # it under the terms of the GNU Affero General Public License as published by + # the Free Software Foundation, either version 3 of the License, or + # (at your option) any later version. + # + # This program is distributed in the hope that it will be useful, + # but WITHOUT ANY WARRANTY; without even the implied warranty of + # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + # GNU Affero General Public License for more details. + # + # You should have received a copy of the GNU Affero General Public License + # along with this program. If not, see . + #} Assets -======= +------ Put any files, such as images, CSS, etc, that are specific to your theme in here. -You can reference these in your templates like so: +You can reference these in your templates like so:: @@ -207,17 +212,17 @@ This will tell MediaGoblin to reference this image from the current theme. Licensing file(s) -================= +----------------- You should include AGPLv3.txt with your theme as this is required for -the assets. You can copy this from mediagoblin/licenses/ +the assets. You can copy this from ``mediagoblin/licenses/``. In the above example, we also use CC0 to waive our copyrights to images and css, so we also included CC0_1.0.txt A README.txt file -================= +----------------- A readme file is not strictly required, but probably a good idea. You can put whatever in here, but restating the license choice clearly is @@ -225,21 +230,21 @@ probably a good idea. Simple theming by adding CSS -============================ +---------------------------- Many themes won't require anything other than the ability to override some of MediaGoblin's core css. Thankfully, doing so is easy if you combine the above steps! In your theme, do the following (make sure you make the necessary -directories and cd to your theme's directory first): +directories and cd to your theme's directory first):: - $ cp /path/to/mediagoblin/mediagoblin/templates/mediagoblin/extra_head.html templates/mediagoblin/ + $ cp /path/to/mediagoblin/mediagoblin/templates/mediagoblin/extra_head.html templates/mediagoblin/ -Great, now open that file and add something like this at the end: +Great, now open that file and add something like this at the end:: - + You can name the css file whatever you like. Now make the directory for assets/css/ and add the file assets/css/theme.css @@ -249,13 +254,13 @@ override default MediaGoblin CSS. Packaging it up! -================ +---------------- Packaging a theme is really easy. It's just a matter of making an archive! -Change to the installed themes directory and run the following: +Change to the installed themes directory and run the following:: - tar cvfz yourtheme.tar.gz yourtheme + tar cvfz yourtheme.tar.gz yourtheme Where "yourtheme" is replaced with your theme name. -- cgit v1.2.3 From 05e007c1dbe7b5b8a092f1a99ed361c4e6b71f26 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Tue, 17 Jul 2012 21:02:12 -0400 Subject: Rework plugin infrastructure to nix side-effects This reworks the plugin infrastructure so as to remove module-loading side-effects which were making things a pain in the ass to test. With the new system, there's no auto-registering meta class. Instead plugins do whatever they want and then specify a hooks dict that maps hook names to callables for the things they're tying into. The most common one (and the only one we've implemented so far) is "setup". This also simplifies the sampleplugin a little by moving the code to __init__.py. --- docs/source/pluginwriter/quickstart.rst | 47 +++++++++++++++------------------ 1 file changed, 22 insertions(+), 25 deletions(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/quickstart.rst b/docs/source/pluginwriter/quickstart.rst index 73531381..b5a63f79 100644 --- a/docs/source/pluginwriter/quickstart.rst +++ b/docs/source/pluginwriter/quickstart.rst @@ -50,7 +50,8 @@ The inner ``sampleplugin`` directory is the Python package that holds your plugin's code. The ``__init__.py`` denotes that this is a Python package. It also -holds the plugin code. +holds the plugin code and the ``hooks`` dict that specifies which +hooks the sampleplugin uses. Step 2: README @@ -107,43 +108,39 @@ The code for ``__init__.py`` looks like this: .. code-block:: python :linenos: - :emphasize-lines: 8,19 + :emphasize-lines: 12,23 import logging from mediagoblin.tools.pluginapi import Plugin, get_config + # This creates a logger that you can use to log information to + # the console or a log file. _log = logging.getLogger(__name__) - class SamplePlugin(Plugin): - """ - This is a sample plugin class. It automatically registers itself - with MediaGoblin when this module is imported. + # This is the function that gets called when the setup + # hook fires. + def setup_plugin(): + _log.info("I've been started!") + config = get_config('sampleplugin') + if config: + _log.info('%r' % config) + else: + _log.info('There is no configuration set.') - The setup_plugin method prints configuration for this plugin if - there is any. - """ - def __init__(self): - pass - def setup_plugin(self): - _log.info("I've been started!") - config = get_config('sampleplugin') - if config: - _log.info('%r' % config) - else: - _log.info('There is no configuration set.') + # This is a dict that specifies which hooks this plugin uses. + # This one only uses one hook: setup. + hooks = { + 'setup': setup_plugin + } -Line 8 defines a class called ``SamplePlugin`` that subclasses -``Plugin`` from ``mediagoblin.tools.pluginapi``. When the class is -defined, it gets registered with MediaGoblin and MediaGoblin will then -call ``setup_plugin`` on it. +Line 12 defines the ``setup_plugin`` function. -Line 19 defines ``setup_plugin``. This gets called when MediaGoblin -starts up after it's registered all the plugins. This is where you can -do any initialization for your plugin. +Line 23 defines ``hooks``. When MediaGoblin loads this file, it sees +``hooks`` and registers all the callables with their respective hooks. Step 6: Installation and configuration -- cgit v1.2.3 From 05d8f314c639f30a699c63e3d4f8feae9a5ba60b Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Tue, 17 Jul 2012 21:14:45 -0400 Subject: [Issue 466] Implement e-z plugin disabling --- docs/source/siteadmin/plugins.rst | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst index 41f2970f..f5a78da7 100644 --- a/docs/source/siteadmin/plugins.rst +++ b/docs/source/siteadmin/plugins.rst @@ -135,3 +135,35 @@ For plugins that you install with pip, you can upgrade them with pip:: pip install -U The ``-U`` tells pip to upgrade the package. + + +Troubleshooting plugins +======================= + +Sometimes plugins just don't work right. When you're having problems +with plugins, think about the following: + +1. Check the log files. + + Some plugins will log errors to the log files and you can use that + to diagnose the problem. + +2. Try running MediaGoblin without that plugin. + + It's easy to disable a plugin from MediaGoblin. Add a ``-`` to the + name in your config file. + + For example, change:: + + [[mediagoblin.plugins.flatpages]] + + to:: + + [[-mediagoblin.plugins.flatpages]] + + That'll prevent the ``mediagoblin.plugins.flatpages`` plugin from + loading. + +3. If it's a core plugin that comes with MediaGoblin, ask us for help! + + If it's a plugin you got from somewhere else, ask them for help! -- cgit v1.2.3 From 4d1761d22fd9c6f2e0ee533236c47bb1ba51f507 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 26 Jul 2012 21:33:25 -0400 Subject: Tweak theming docs I did a pass on language and more reST formatting. This is a little cleaner, though there are a couple of parts that feel like they could use some work. --- docs/source/siteadmin/theming.rst | 104 ++++++++++++++++++++------------------ 1 file changed, 55 insertions(+), 49 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index 74bc80dc..b22de727 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -17,43 +17,46 @@ Theming MediaGoblin ===================== -We try to provide a nice theme for MediaGoblin by default. But of +We try to provide a nice theme for MediaGoblin by default, but of course, you might want something different! Maybe you want something more light and colorful, or maybe you want something specifically -tailored to your organization. Have no fear, MediaGoblin has theming -support! This guide should walk you through installing and making themes. +tailored to your organization. Have no fear---MediaGoblin has theming +support! This guide should walk you through installing and making +themes. Installing a theme ================== +.. _theming-installing-section: + Installing the archive ---------------------- -Say you have a theme archive such as goblincities.tar.gz. You want to -install this theme! Don't worry, it's fairly painless. +Say you have a theme archive such as ``goblincities.tar.gz`` and you +want to install this theme! Don't worry, it's fairly painless. -Simply cd to the "install directory" for themes (by default, -``./user_dev/themes/`` relative to the mediagoblin install directory... to -configure these things, see the next section), move the archive there, -and decompress:: +1. ``cd ./user_dev/themes/`` - $ tar xvfz goblincities.tar.gz +2. Move the theme archive into this directory -Next, open up your mediagoblin configuration file (probably -``mediagoblin_local.ini``) and set the theme name:: +3. ``tar -xzvf `` - [mediagoblin] - # ... - theme = goblincities +4. Open your configuration file (probably named + ``mediagoblin_local.ini``) and set the theme name:: + + [mediagoblin] + # ... + theme = goblincities -Finally, "link the assets" so that they can be served by your web -server:: +5. Link the assets so that they can be served by your web server:: - $ ./bin/gmg theme assetlink + $ ./bin/gmg theme assetlink -Note, if you ever change the current theme in your config file, you -should re-run the above command! +.. Note:: + + If you ever change the current theme in your config file, you + should re-run the above command! (In the near future this should be even easier ;)) @@ -70,7 +73,7 @@ should re-run the above command! Set up your webserver to serve theme assets ------------------------------------------- -Section to be written, ask on #mediagoblin in irc.freenode.net in the +FIXME - To be written. Ask on #mediagoblin in irc.freenode.net in the meanwhile ;) @@ -78,10 +81,11 @@ Configuring where things go --------------------------- By default, MediaGoblin's install directory for themes is -./user_dev/themes/ (relative to the MediaGoblin checkout or base -config file.) However, you can change this location easily. In your -mediagoblin config file, under the section [mediagoblin] set the -following parameter:: +``./user_dev/themes/`` (relative to the MediaGoblin checkout or base +config file.) However, you can change this location easily with the +``theme_install_dir`` setting in the ``[mediagoblin]`` section. + +For example:: [mediagoblin] # ... other parameters go here ... @@ -98,8 +102,8 @@ Other variables you may consider setting: `theme_linked_assets_dir` Your web server needs to serve the theme files out of some directory, - and MediaGoblin will symlink the current theme's assets here. (See - "Linking assets" in the theme install section) + and MediaGoblin will symlink the current theme's assets here. See + the "Link the assets" setp in :ref:`theming-installing-section`. Making a theme @@ -109,36 +113,38 @@ Okay, so a theme layout is pretty simple. Let's assume we're making a theme for an instance about hedgehogs! We'll call this the "hedgehogified" theme. -Change to where your theme_install_dir is set to (by default, -``./user_dev/themes/`` ... make those directories if necessary and -otherwise adjust if necessary):: +Change to where your ``theme_install_dir`` is set to (by default, +``./user_dev/themes/`` ... make those directories or otherwise adjust +if necessary):: hedgehogified/ - |- theme.cfg # configuration file for this theme - |- templates/ # override templates + |- theme.cfg # configuration file for this theme + |- templates/ # override templates | '- mediagoblin/ - | |- base.html # overriding mediagoblin/base.html - | '- root.html # overriding mediagoblin/root.html + | |- base.html # overriding mediagoblin/base.html + | '- root.html # overriding mediagoblin/root.html '- assets/ | '- images/ - | | |- im_a_hedgehog.png # hedgehog-containing image used by theme - | | '- custom_logo.png # your theme's custom logo + | | |- im_a_hedgehog.png # hedgehog-containing image used by theme + | | '- custom_logo.png # your theme's custom logo | '- css/ - | '- hedgehog.css # your site's hedgehog-specific css - |- README.txt # Optionally, a readme file (not required) - |- AGPLv3.txt # AGPL license file for your theme. (good practice) - '- CC0_1.0.txt # CC0 1.0 legalcode for the assets [if appropriate!] + | '- hedgehog.css # your site's hedgehog-specific css + |- README.txt # Optionally, a readme file (not required) + |- AGPLv3.txt # AGPL license file for your theme. (good practice) + '- CC0_1.0.txt # CC0 1.0 legalcode for the assets [if appropriate!] The top level directory of your theme should be the symbolic name for your theme. This is the name that users will use to refer to activate your theme. -It's important to note that templates based on MediaGoblin's code -should be released as AGPLv3 (or later), like MediaGoblin's code -itself. However, all the rest of your assets are up to you. In this -case, we are waiving our copyright for images and CSS into the public -domain via CC0 (as MediaGoblin does) but do what's appropriate to you. +.. Note:: + + It's important to note that templates based on MediaGoblin's code + should be released as AGPLv3 (or later), like MediaGoblin's code + itself. However, all the rest of your assets are up to you. In this + case, we are waiving our copyright for images and CSS into the public + domain via CC0 (as MediaGoblin does) but do what's appropriate to you. The config file @@ -177,7 +183,7 @@ this matter if you wish. To fit with best licensing form, you should either preserve the MediaGoblin copyright header borrowing from a MediaGoblin template, or -you may include one like the following if a new file:: +you may include one like the following:: {# # [YOUR THEME], a MediaGoblin theme @@ -224,7 +230,7 @@ images and css, so we also included CC0_1.0.txt A README.txt file ----------------- -A readme file is not strictly required, but probably a good idea. You +A README file is not strictly required, but probably a good idea. You can put whatever in here, but restating the license choice clearly is probably a good idea. @@ -247,7 +253,7 @@ Great, now open that file and add something like this at the end:: href="{{ request.staticdirect('/css/theme.css', 'theme') }}"/> You can name the css file whatever you like. Now make the directory -for assets/css/ and add the file assets/css/theme.css +for ``assets/css/`` and add the file ``assets/css/theme.css``. You can now put custom CSS files in here and any CSS you add will override default MediaGoblin CSS. @@ -260,7 +266,7 @@ Packaging a theme is really easy. It's just a matter of making an archive! Change to the installed themes directory and run the following:: - tar cvfz yourtheme.tar.gz yourtheme + tar -cvfz yourtheme.tar.gz yourtheme Where "yourtheme" is replaced with your theme name. -- cgit v1.2.3 From 8d051cc0854c1a82d6f12251295ee44d0d463713 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 27 Jul 2012 08:45:35 -0500 Subject: Add documentation on how to alias your theme static files --- docs/source/siteadmin/deploying.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 788b06d7..c9a429c7 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -283,6 +283,11 @@ this ``nginx.conf`` file should be modeled on the following:: alias /srv/mediagoblin.example.org/mediagoblin/user_dev/media/public/; } + # Theme static files (usually symlinked in) + location /theme_static/ { + alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/; + } + # Mounting MediaGoblin itself via FastCGI. location / { fastcgi_pass 127.0.0.1:26543; -- cgit v1.2.3 From cd1abb1172462488c47730d95e4484ea642bb3ba Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 27 Jul 2012 09:02:07 -0500 Subject: Reference the new theme aliasing nginx stuff in the theming documentation --- docs/source/siteadmin/deploying.rst | 2 ++ docs/source/siteadmin/theming.rst | 12 ++++++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index c9a429c7..de928c82 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -222,6 +222,8 @@ test the deployment with the following command:: You should be able to connect to the machine on port 6543 in your browser to confirm that the service is operable. +.. _webserver-config: + Connect the Webserver to MediaGoblin with FastCGI ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index b22de727..b21e2743 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -73,8 +73,16 @@ want to install this theme! Don't worry, it's fairly painless. Set up your webserver to serve theme assets ------------------------------------------- -FIXME - To be written. Ask on #mediagoblin in irc.freenode.net in the -meanwhile ;) +If you followed the nginx setup example in :ref:`webserver-config` you +should already have theme asset setup. However, if you set up your +server config with an older version of mediagoblin and the mediagoblin +docs, it's possible you don't have the "theme static files" alias, so +double check to make sure that section is there if you are having +problems. + +If you are simply using this for local development and serving the +whole thing via paste/lazyserver, assuming you don't have a +paste_local.ini, the asset serving should be done for you. Configuring where things go -- cgit v1.2.3 From 8d9aa03fbae7c1164942d05602c41cb635a44395 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 5 Aug 2012 10:14:15 -0500 Subject: Fixing grammar on telling users to run dbupdate --- docs/source/siteadmin/deploying.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index de928c82..a270c723 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -181,7 +181,7 @@ flup:: ./bin/easy_install flup This concludes the initial configuration of the development -environment. In the future, you want update your +environment. In the future, when you update your codebase, you should also run:: ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate -- cgit v1.2.3 From fafef8df2e240c3b127386af04425cca33b3d84e Mon Sep 17 00:00:00 2001 From: Aleksej Date: Sat, 18 Aug 2012 23:31:27 +0400 Subject: add titles to two pages and fix a typo in docs --- docs/source/siteadmin/theming.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index b21e2743..98ec6de7 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -111,7 +111,7 @@ Other variables you may consider setting: `theme_linked_assets_dir` Your web server needs to serve the theme files out of some directory, and MediaGoblin will symlink the current theme's assets here. See - the "Link the assets" setp in :ref:`theming-installing-section`. + the "Link the assets" step in :ref:`theming-installing-section`. Making a theme -- cgit v1.2.3 From 7a690a5ae541f26321be98625a3df34847b44d5b Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 20 Aug 2012 08:54:09 -0500 Subject: Updated flatpages example in plugins.rst to reflect reality & point to flatpages docs --- docs/source/siteadmin/plugins.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst index f5a78da7..594461c0 100644 --- a/docs/source/siteadmin/plugins.rst +++ b/docs/source/siteadmin/plugins.rst @@ -79,14 +79,18 @@ should come with documentation that tells you how to configure them. Example 1: Core MediaGoblin plugin If you wanted to use the core MediaGoblin flatpages plugin, the module -for that is ``mediagoblin.plugins.flatpages`` and you would add that -to your ``.ini`` file like this:: +for that is ``mediagoblin.plugins.flatpagesfile`` and you would add +that to your ``.ini`` file like this:: [plugins] - [[mediagoblin.plugins.flatpages]] - # configuration for flatpages plugin here! - directory = /srv/mediagoblin/flatpages + [[mediagoblin.plugins.flatpagesfile]] + # configuration for flatpagesfile plugin here! + about-view = '/about', about.html + terms-view = '/terms', terms.html + +(Want to know more about the flatpagesfile plugin? See +:ref:`flatpagesfile-chapter`) Example 2: Plugin that is not a core MediaGoblin plugin -- cgit v1.2.3 From 3a438f5e84cef433d5c396f14dec8cd8a713e93c Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 20 Aug 2012 12:35:35 -0400 Subject: Docs tweaks This fixes some minor issues in the documentation. --- docs/source/siteadmin/configuration.rst | 10 ++++++---- docs/source/siteadmin/plugins.rst | 6 +++--- docs/source/siteadmin/relnotes.rst | 6 ++++++ 3 files changed, 15 insertions(+), 7 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/configuration.rst b/docs/source/siteadmin/configuration.rst index a3dafa4c..3da5cdd9 100644 --- a/docs/source/siteadmin/configuration.rst +++ b/docs/source/siteadmin/configuration.rst @@ -117,13 +117,15 @@ To be perfectly honest, there are quite a few options and we haven't had time to document them all. So here's a cop-out section saying that if you get into trouble, hop -onto IRC and we'll help you out:: +onto IRC and we'll help you out. Details for the IRC channel is on the +`join page`_ of the website. + +.. _join page: http://mediagoblin.org/join/ + - #mediagoblin on irc.freenode.net Celery ====== -We should point to another celery-specific section of the document -actually :) +FIXME: List Celery configuration here. diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst index 594461c0..75562d4b 100644 --- a/docs/source/siteadmin/plugins.rst +++ b/docs/source/siteadmin/plugins.rst @@ -159,13 +159,13 @@ with plugins, think about the following: For example, change:: - [[mediagoblin.plugins.flatpages]] + [[mediagoblin.plugins.flatpagesfile]] to:: - [[-mediagoblin.plugins.flatpages]] + [[-mediagoblin.plugins.flatpagesfile]] - That'll prevent the ``mediagoblin.plugins.flatpages`` plugin from + That'll prevent the ``mediagoblin.plugins.flatpagesfile`` plugin from loading. 3. If it's a core plugin that comes with MediaGoblin, ask us for help! diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 2efded73..025008fd 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -20,6 +20,12 @@ If you're upgrading from a previous release, please read it carefully, or at least skim over it. +0.3.1 +===== + +FIXME: Needs to be written + + 0.3.0 ===== -- cgit v1.2.3 From 0346518e35e76b56ac1effcfdea7f8d9596b3333 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Tue, 21 Aug 2012 15:37:16 -0500 Subject: Release notes for 0.3.1 --- docs/source/siteadmin/relnotes.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 025008fd..e0d28656 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -23,7 +23,17 @@ carefully, or at least skim over it. 0.3.1 ===== -FIXME: Needs to be written +As usual in this release you should be sure to run `bin/gmg dbupdate` +to upgrade the database to the latest schema. There are not major +changes other than this that you need to do to make your present +MediaGoblin instance continue to work. + +However, MediaGoblin now also includes theming support, which you can +read about in the section :ref:`_theming_chapter`. If you set up your +server config with an older version of mediagoblin and the mediagoblin +docs, it's possible you don't have the "theme static files" alias, so +double check to make sure that section is there if you are having +problems. 0.3.0 -- cgit v1.2.3 From 9e579cde816397be5a680725f86f7c3a0d603810 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 22 Aug 2012 17:47:15 -0400 Subject: Fix relnotes for 0.3.1. --- docs/source/index.rst | 2 ++ docs/source/siteadmin/relnotes.rst | 36 +++++++++++++++++++++++++----------- 2 files changed, 27 insertions(+), 11 deletions(-) (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index fa637e95..6671a6e3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -47,6 +47,8 @@ MediaGoblin website. It is written for site administrators. siteadmin/codebase +.. _core-plugin-section: + Part 2: Core plugin documentation ================================= diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index e0d28656..1b70b31c 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -23,17 +23,31 @@ carefully, or at least skim over it. 0.3.1 ===== -As usual in this release you should be sure to run `bin/gmg dbupdate` -to upgrade the database to the latest schema. There are not major -changes other than this that you need to do to make your present -MediaGoblin instance continue to work. - -However, MediaGoblin now also includes theming support, which you can -read about in the section :ref:`_theming_chapter`. If you set up your -server config with an older version of mediagoblin and the mediagoblin -docs, it's possible you don't have the "theme static files" alias, so -double check to make sure that section is there if you are having -problems. +**Do this to upgrade** + +1. Make sure to run ``bin/gmg dbuptdate`` after upgrading. + +2. If you set up your server config with an older version of + mediagoblin and the mediagoblin docs, it's possible you don't + have the "theme static files" alias, so double check to make + sure that section is there if you are having problems. + + + +**New features** + +* **theming support** + + MediaGoblin now also includes theming support, which you can + read about in the section :ref:`theming-chapter`. + +* **flatpages** + + MediaGoblin has a flatpages plugin allowing you to add pages that + are aren't media-related like "About this site...", "Terms of + service...", etc. + + See :ref:`core-plugin-section` for plugin documentation 0.3.0 -- cgit v1.2.3 From 9454f6c85675f6d8fc0345bdfbb7f83180a9c15d Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Wed, 22 Aug 2012 18:04:50 -0400 Subject: Fix docs so they pull version from _version.py --- docs/source/conf.py | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 41cf2529..4209acc8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -17,6 +17,7 @@ import sys, os # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.abspath(os.path.join('..', '..'))) # -- General configuration ----------------------------------------------------- @@ -47,10 +48,15 @@ copyright = u'2011, 2012 GNU MediaGoblin contributors' # |version| and |release|, also used in various other places throughout the # built documents. # -# The short X.Y version. -version = '0.3.1' -# The full version, including alpha/beta/rc tags. -release = '0.3.1.dev' +try: + from mediagoblin._version import __version__ + # The short X.Y version. + version = '.'.join(__version__.split('.')[0:2]) + # The full version, including alpha/beta/rc tags. + release = __version__ +except ImportError: + version = 'unknown' + release = 'unknown' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From df3147b986b183198d6419c50ca743e4f0c1bdea Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Tue, 18 Sep 2012 21:42:10 +0200 Subject: Added documentation for the OAuth plugin --- docs/source/index.rst | 1 + docs/source/plugindocs/oauth.rst | 1 + 2 files changed, 2 insertions(+) create mode 100644 docs/source/plugindocs/oauth.rst (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index 6671a6e3..ac8bd110 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -57,6 +57,7 @@ Part 2: Core plugin documentation plugindocs/flatpagesfile plugindocs/sampleplugin + plugindocs/oauth Part 3: Plugin Writer's Guide diff --git a/docs/source/plugindocs/oauth.rst b/docs/source/plugindocs/oauth.rst new file mode 100644 index 00000000..0685c9d1 --- /dev/null +++ b/docs/source/plugindocs/oauth.rst @@ -0,0 +1 @@ +.. include:: ../../../mediagoblin/plugins/oauth/README.rst -- cgit v1.2.3 From 34a853133f6b5aa4a368053489c7c7f2838eec2b Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Sat, 29 Sep 2012 20:35:49 +0200 Subject: Added note about libasound2-dev to docs. --- docs/source/siteadmin/media-types.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index d062da95..40e54c56 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -96,6 +96,13 @@ On Debianoid systems, run:: sudo apt-get install libsndfile1-dev +.. note:: + scikits.audiolab will display a warning every time it's imported if you don + not compile it with alsa support. Alsa support is not necessary for the GNU + MediaGoblin application, but if you do not wish to have the alsa warnings + from audiolab pop up everywhere you should also install ``libasound2-dev`` + before you install scikits.audiolab. + Then install ``scikits.audiolab`` for the spectrograms:: ./bin/pip install scikits.audiolab -- cgit v1.2.3 From 8518e95eb64ff2864d7880f8bfff9df1828fb848 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Sat, 29 Sep 2012 20:39:17 +0200 Subject: Grammar re: libasound2-dev --- docs/source/siteadmin/media-types.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 40e54c56..5653217f 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -97,11 +97,11 @@ On Debianoid systems, run:: sudo apt-get install libsndfile1-dev .. note:: - scikits.audiolab will display a warning every time it's imported if you don + scikits.audiolab will display a warning every time it's imported if you do not compile it with alsa support. Alsa support is not necessary for the GNU - MediaGoblin application, but if you do not wish to have the alsa warnings - from audiolab pop up everywhere you should also install ``libasound2-dev`` - before you install scikits.audiolab. + MediaGoblin application but if you do not wish the alsa warnings from + audiolab you should also install ``libasound2-dev`` before installing + scikits.audiolab. Then install ``scikits.audiolab`` for the spectrograms:: -- cgit v1.2.3 From 4d8a3cd808a309b250df40f64bb862fdb5ede434 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 19 Nov 2012 12:17:44 -0600 Subject: Suggest checking out the wiki for additional recipes --- docs/source/siteadmin/deploying.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index a270c723..dc0a4c67 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -32,6 +32,11 @@ GNU/Linux distro. install. If instead you want to join in as a contributor, see our `Hacking HOWTO `_ instead. + There are also many ways to install servers... for the sake of + simplicity, our instructions below describe installing with nginx. + For more recipes, including Apache, see + `our wiki `_. + Prepare System -------------- -- cgit v1.2.3 From 60389b21f5d24acf6faf08c225da16b3f8d7de18 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Tue, 20 Nov 2012 09:25:41 +0100 Subject: Purge routes package from MG (#507) We were not actually using the routes package anymore, but it was still mentioned in the documention. Adapt the plugin documentation to actually represent reality, although I don't like the API design. (but this is for another day) Signed-off-by: Sebastian Spaeth --- docs/source/siteadmin/codebase.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/codebase.rst b/docs/source/siteadmin/codebase.rst index 3ef91290..22f4e18b 100644 --- a/docs/source/siteadmin/codebase.rst +++ b/docs/source/siteadmin/codebase.rst @@ -68,8 +68,6 @@ Software Stack * `WebOb `_: nice abstraction layer from HTTP requests, responses and WSGI bits - * `Routes `_: for URL routing - * `Beaker `_: for handling sessions and caching -- cgit v1.2.3 From c356dc16351b33cc60cc95d6a5836ffaceffc5eb Mon Sep 17 00:00:00 2001 From: Elrond Date: Tue, 20 Nov 2012 14:32:29 +0100 Subject: Very small typo fix in deploying docs. Thanks to #mediagoblin. --- docs/source/siteadmin/deploying.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index dc0a4c67..0eb67be4 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -170,7 +170,7 @@ And set up the in-package virtualenv:: If you have problems here, consider trying to install virtualenv with the ``--distribute`` or ``--no-site-packages`` options. If - your system's default Python is in the 3.x series you man need to + your system's default Python is in the 3.x series you may need to run ``virtualenv`` with the ``--python=python2.7`` or ``--python=python2.6`` options. @@ -178,7 +178,7 @@ The above provides an in-package install of ``virtualenv``. While this is counter to the conventional ``virtualenv`` configuration, it is more reliable and considerably easier to configure and illustrate. If you're familiar with Python packaging you may consider deploying with -your preferred the method. +your preferred method. Assuming you are going to deploy with FastCGI, you should also install flup:: -- cgit v1.2.3 From 7989cd6e4961749a39147c9020dbae745b4f23de Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sat, 1 Dec 2012 20:31:18 +0100 Subject: docs: Add trim_whitespaces plugin to relnotes and documentation Rather than mentioning a hypothetical module restrictfive, we use the existing plugin mediagoblin-licenses that people can install. Also, mention that plugin in the release notes. Signed-off-by: Sebastian Spaeth --- docs/source/siteadmin/plugins.rst | 22 +++++++++++++--------- docs/source/siteadmin/relnotes.rst | 6 ++++++ 2 files changed, 19 insertions(+), 9 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/plugins.rst b/docs/source/siteadmin/plugins.rst index 75562d4b..baca381d 100644 --- a/docs/source/siteadmin/plugins.rst +++ b/docs/source/siteadmin/plugins.rst @@ -44,29 +44,33 @@ If the plugin is available on the `Python Package Index pip install For example, if we wanted to install the plugin named -"mediagoblin-restrictfive", we would do:: +"mediagoblin-licenses" (which allows you to customize the licenses you +offer for your media), we would do:: - pip install mediagoblin-restrictfive + pip install mediagoblin-licenses .. Note:: If you're using a virtual environment, make sure to activate the - virtual environment before installing with pip. Otherwise the - plugin may get installed in a different environment than the one - MediaGoblin is installed in. + virtual environment before installing with pip. Otherwise the plugin + may get installed in a different environment than the one MediaGoblin + is installed in. Also make sure, you use e.g. pip-2.7 if your default + python (and thus pip) is python 3 (e.g. in Ubuntu). Once you've installed the plugin software, you need to tell MediaGoblin that this is a plugin you want MediaGoblin to use. To do that, you edit the ``mediagoblin.ini`` file and add the plugin as a subsection of the plugin section. -For example, say the "mediagoblin-restrictfive" plugin had the Python -package path ``restrictfive``, then you would add ``restrictfive`` to +For example, say the "mediagoblin-licenses" plugin has the Python +package path ``mediagoblin_licenses``, then you would add ``mediagoblin_licenses`` to the ``plugins`` section as a subsection:: [plugins] - [[restrictfive]] + [[mediagoblin_licenses]] + license_01=abbrev1, name1, http://url1 + license_02=abbrev2, name1, http://url2 Configuring plugins @@ -112,7 +116,7 @@ Removing plugins To remove a plugin, use ``pip uninstall``. For example:: - pip uninstall mediagoblin-restrictfive + pip uninstall mediagoblin-licenses .. Note:: diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 1b70b31c..56267eb1 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -49,6 +49,12 @@ carefully, or at least skim over it. See :ref:`core-plugin-section` for plugin documentation +* **trim_whitespace** + + We bundle the optional plugin trim_whitespace which reduces the size + of the delivered html output by reducing redundant whitespace. + + See :ref:`core-plugin-section` for plugin documentation 0.3.0 ===== -- cgit v1.2.3 From 9d5cd0b924fe790d27b4941c5d226fc7bde03741 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 14 Dec 2012 18:29:00 -0600 Subject: Adding info to the docs about running dbupdate Both adding info to run it when adding new media types, and adding info that you might need to stop mediagoblin before you run these commands. --- docs/source/siteadmin/deploying.rst | 6 ++++++ docs/source/siteadmin/media-types.rst | 9 +++++++++ 2 files changed, 15 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 0eb67be4..91406f96 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -191,6 +191,12 @@ codebase, you should also run:: ./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate +Note: If you are running an active site, depending on your server +configuration, you may need to stop it first or the dbupdate command +may hang (and it's certainly a good idea to restart it after the +update) + + Deploy MediaGoblin Services --------------------------- diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 5653217f..3b46c1b6 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -43,6 +43,15 @@ video media types, then the list would look like this:: media_types = mediagoblin.media_types.image, mediagoblin.media_types.video +Note that after enabling new media types, you must run dbupdate like so:: + + ./bin/gmg dbupdate + +If you are running an active site, depending on your server +configuration, you may need to stop it first (and it's certainly a +good idea to restart it after the update). + + How does MediaGoblin decide which media type to use for a file? =============================================================== -- cgit v1.2.3 From cacb6feae48fd2657f02d85dbe949580d0fa6b5b Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sat, 15 Dec 2012 21:00:41 +0100 Subject: Release note 0.3.2 blurb On MongoDB... --- docs/source/siteadmin/relnotes.rst | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 56267eb1..3e09078e 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -19,6 +19,24 @@ This chapter has important information for releases in it. If you're upgrading from a previous release, please read it carefully, or at least skim over it. +0.3.2 +===== + +This will be the last release that is capable of converting from an earlier +MongoDB-based MediaGoblin instance to the newer SQL-based system. + + +**New features** + +* TO BE FILLED IN BEFORE RELEASE :-) + +* **trim_whitespace** + + We bundle the optional plugin trim_whitespace which reduces the size + of the delivered html output by reducing redundant whitespace. + + See :ref:`core-plugin-section` for plugin documentation + 0.3.1 ===== @@ -49,12 +67,6 @@ carefully, or at least skim over it. See :ref:`core-plugin-section` for plugin documentation -* **trim_whitespace** - - We bundle the optional plugin trim_whitespace which reduces the size - of the delivered html output by reducing redundant whitespace. - - See :ref:`core-plugin-section` for plugin documentation 0.3.0 ===== -- cgit v1.2.3 From 5ef7ab084f246b81897e248590be3a61898adc77 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 20 Dec 2012 08:18:19 -0600 Subject: Added documentation on how to add STL support, and notes on running ./bin/gmg dbupdate --- docs/source/siteadmin/media-types.rst | 36 +++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 3b46c1b6..26852842 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -77,6 +77,12 @@ good/bad/ugly). On Debianoid systems:: gstreamer0.10-ffmpeg +Add ``mediagoblin.media_types.video`` to the ``media_types`` list in your +``mediagoblin_local.ini`` and restart MediaGoblin. + +Run:: + ./bin/gmg dbupdate + Now you should be able to submit videos, and mediagoblin should transcode them. @@ -117,8 +123,12 @@ Then install ``scikits.audiolab`` for the spectrograms:: ./bin/pip install scikits.audiolab Add ``mediagoblin.media_types.audio`` to the ``media_types`` list in your -``mediagoblin_local.ini`` and restart MediaGoblin. You should now be able to -upload and listen to audio files! +``mediagoblin_local.ini`` and restart MediaGoblin. + +Run:: + ./bin/gmg dbupdate + +You should now be able to upload and listen to audio files! Ascii art @@ -140,4 +150,26 @@ the list would look like this:: media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii +Run:: + ./bin/gmg dbupdate + Now any .txt file you uploaded will be processed as ascii art! + + +STL / 3d model support +====================== + +To enable the "STL" 3d model support plugin, first make sure you have +a recentish `Blender `_ installed and available on +your execution path. This feature has been tested with Blender 2.63. +It may work on some earlier versions, but that is not guaranteed (and +is surely not to work prior to Blender 2.5X). + +Add ``mediagoblin.media_types.stl`` to the ``media_types`` list in your +``mediagoblin_local.ini`` and restart MediaGoblin. + +Run:: + ./bin/gmg dbupdate + +You should now be able to upload .obj and .stl files and MediaGoblin +will be able to present them to your wide audience of admirers! -- cgit v1.2.3 From 3fe3b2229c82fd894bc4d3e8effdf26cfc7780ea Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 20 Dec 2012 08:22:49 -0600 Subject: Docs fix: Adding proper blank line after the "Run::" --- docs/source/siteadmin/media-types.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 26852842..8fbce5e4 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -81,6 +81,7 @@ Add ``mediagoblin.media_types.video`` to the ``media_types`` list in your ``mediagoblin_local.ini`` and restart MediaGoblin. Run:: + ./bin/gmg dbupdate Now you should be able to submit videos, and mediagoblin should @@ -126,6 +127,7 @@ Add ``mediagoblin.media_types.audio`` to the ``media_types`` list in your ``mediagoblin_local.ini`` and restart MediaGoblin. Run:: + ./bin/gmg dbupdate You should now be able to upload and listen to audio files! @@ -151,6 +153,7 @@ the list would look like this:: media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii Run:: + ./bin/gmg dbupdate Now any .txt file you uploaded will be processed as ascii art! @@ -169,6 +172,7 @@ Add ``mediagoblin.media_types.stl`` to the ``media_types`` list in your ``mediagoblin_local.ini`` and restart MediaGoblin. Run:: + ./bin/gmg dbupdate You should now be able to upload .obj and .stl files and MediaGoblin -- cgit v1.2.3 From 1f01df1dfc891e900e659db84ef840138b60d160 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 20 Dec 2012 09:48:47 -0600 Subject: 0.3.2 release notes --- docs/source/siteadmin/relnotes.rst | 59 +++++++++++++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 3e09078e..ef164cbb 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -25,10 +25,18 @@ carefully, or at least skim over it. This will be the last release that is capable of converting from an earlier MongoDB-based MediaGoblin instance to the newer SQL-based system. +**Do this to upgrade** + +1. Make sure to run ``bin/gmg dbuptdate`` after upgrading. + **New features** -* TO BE FILLED IN BEFORE RELEASE :-) +* **3d model support!** + + You can now upload STL and OBJ files and display them in + MediaGoblin. Requires a recent-ish Blender; for details see: + :ref:`deploying-chapter` * **trim_whitespace** @@ -37,6 +45,55 @@ MongoDB-based MediaGoblin instance to the newer SQL-based system. See :ref:`core-plugin-section` for plugin documentation +* **A new API!** + + It isn't well documented yet but we do have an API. There is an + `android application in progress `_ + which makes use of it, and there are some demo applications between + `automgtic `_, an + automatic media uploader for your desktop + and `OMGMG `_, an example of + a web application hooking up to the API. + + This is a plugin, so you have to enable it in your mediagoblin + config file by adding a section under [plugins] like:: + + [plugins] + [[mediagoblin.plugins.api]] + + Note that the API works but is not nailed down... the way it is + called may change in future releases. + +* **OAuth login support** + + For applications that use OAuth to connect to the API. + + This is a plugin, so you have to enable it in your mediagoblin + config file by adding a section under [plugins] like:: + + [plugins] + [[mediagoblin.plugins.oauth]] + +* **Collections** + + We now have user-curated collections support. These are arbitrary + galleries that are customizable by users. You can add media to + these by clicking on the paperclip icon when logged in and looking + at a media entry. + +* **OpenStreetMap licensing display improvements** + + More accurate display of OSM licensing, and less disruptive: you + click to "expand" the display of said licensing. + + Geolocation is also now on by default. + +* **Miscelaneous visual improvements** + + We've made a number of small visual improvements including newer and + nicer looking thumbnails and improved checkbox placement. + + 0.3.1 ===== -- cgit v1.2.3 From 5c99cd01a70f2d597ac7669e8d944ddf79b05281 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 20 Dec 2012 13:54:03 -0600 Subject: Fixing tyop'ed "dbupdate" --- docs/source/siteadmin/relnotes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index ef164cbb..25d4d83f 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -27,7 +27,7 @@ MongoDB-based MediaGoblin instance to the newer SQL-based system. **Do this to upgrade** -1. Make sure to run ``bin/gmg dbuptdate`` after upgrading. +1. Make sure to run ``bin/gmg dbupdate`` after upgrading. **New features** -- cgit v1.2.3 From 42ce372e38b28d6e01da76b05d6924d04c2710ae Mon Sep 17 00:00:00 2001 From: Mike Linksvayer Date: Thu, 20 Dec 2012 12:52:31 -0800 Subject: actual upgrade instructions --- docs/source/siteadmin/relnotes.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 25d4d83f..55a8279d 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -27,7 +27,19 @@ MongoDB-based MediaGoblin instance to the newer SQL-based system. **Do this to upgrade** -1. Make sure to run ``bin/gmg dbupdate`` after upgrading. + # directory of your mediagoblin install + cd /srv/mediagoblin.example.org + + # copy source for this release + git fetch + git checkout tags/v0.3.2 + + # perform any needed database updates + bin/gmg dbupdate + + # restart your servers however you do that, e.g., + sudo service mediagoblin-paster restart + sudo service mediagoblin-celeryd restart **New features** -- cgit v1.2.3 From 53f528cfeaab5fc146844b6d7d85997c92cfd979 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 15 Nov 2012 16:57:33 +0100 Subject: purge webob from docs and replace with werkzeug --- docs/source/siteadmin/codebase.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/codebase.rst b/docs/source/siteadmin/codebase.rst index 22f4e18b..73e938e7 100644 --- a/docs/source/siteadmin/codebase.rst +++ b/docs/source/siteadmin/codebase.rst @@ -65,7 +65,7 @@ Software Stack `Paste Script `_: we'll use this for configuring and launching the application - * `WebOb `_: nice abstraction layer + * `werkzeug `_: nice abstraction layer from HTTP requests, responses and WSGI bits * `Beaker `_: for handling sessions and -- cgit v1.2.3 From 8d19cb2445e2aa1f53431da26d866bf9b5e25872 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 16 Nov 2012 11:32:35 +0100 Subject: Don't require webob as dependency It is pushing up the daisies. Also relnote the change. --- docs/source/build/mediagoblin-licenses/PKG-INFO | 11 ++++ docs/source/build/mediagoblin-licenses/README | 15 +++++ .../mediagoblin_licenses/README.rst | 15 +++++ .../mediagoblin_licenses/__init__.py | 69 ++++++++++++++++++++++ .../mediagoblin_licenses/README.rst | 15 +++++ .../mediagoblin_licenses/__init__.py | 69 ++++++++++++++++++++++ .../mediagoblin_licenses.egg-info/PKG-INFO | 11 ++++ .../mediagoblin_licenses.egg-info/SOURCES.txt | 6 ++ .../dependency_links.txt | 1 + .../mediagoblin_licenses.egg-info/top_level.txt | 1 + docs/source/build/mediagoblin-licenses/setup.py | 30 ++++++++++ docs/source/build/pip-delete-this-directory.txt | 5 ++ docs/source/plugindocs/trim_whitespace.rst | 1 + docs/source/siteadmin/relnotes.rst | 9 +++ 14 files changed, 258 insertions(+) create mode 100644 docs/source/build/mediagoblin-licenses/PKG-INFO create mode 100644 docs/source/build/mediagoblin-licenses/README create mode 100644 docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/README.rst create mode 100644 docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/__init__.py create mode 100644 docs/source/build/mediagoblin-licenses/mediagoblin_licenses/README.rst create mode 100644 docs/source/build/mediagoblin-licenses/mediagoblin_licenses/__init__.py create mode 100644 docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/PKG-INFO create mode 100644 docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/SOURCES.txt create mode 100644 docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/dependency_links.txt create mode 100644 docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/top_level.txt create mode 100644 docs/source/build/mediagoblin-licenses/setup.py create mode 100644 docs/source/build/pip-delete-this-directory.txt create mode 100644 docs/source/plugindocs/trim_whitespace.rst (limited to 'docs/source') diff --git a/docs/source/build/mediagoblin-licenses/PKG-INFO b/docs/source/build/mediagoblin-licenses/PKG-INFO new file mode 100644 index 00000000..047efe83 --- /dev/null +++ b/docs/source/build/mediagoblin-licenses/PKG-INFO @@ -0,0 +1,11 @@ +Metadata-Version: 1.1 +Name: mediagoblin-licenses +Version: 0.1.2 +Summary: Customize the licenses for your mediagoblin installation +Home-page: https://gitorious.org/mediagoblin-licenses/mediagoblin-licenses +Author: Sebastian Spaeth +Author-email: Sebastian@SSpaeth.de +License: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+) +Download-URL: https://gitorious.org/mediagoblin-licenses/mediagoblin-licenses/archive-tarball/mediagoblin-licenses-v0.1.2 +Description: UNKNOWN +Platform: UNKNOWN diff --git a/docs/source/build/mediagoblin-licenses/README b/docs/source/build/mediagoblin-licenses/README new file mode 100644 index 00000000..ce52a8c0 --- /dev/null +++ b/docs/source/build/mediagoblin-licenses/README @@ -0,0 +1,15 @@ +================ + Custom Licenses +================ + +Enable by configuring all custom licenses in the form of: +license_x=Abbreviation, Full Name, URL to license + +Make sure to only insert one line per license without line breaks. + +E.g. do this into mediagoblin_local.ini: +[[mediagoblin_licenses]] +license_1=Chicken Dance, Chicken Dance License v1.0, https://raw.github.com/supertunaman/cdl/f0ae734f4abce311070ac0c401dbc0230cbc4344/COPYING +license_2=WTFPL, Do What the Fuck Public License v2.0, http://sam.zoy.org/wtfpl/ + +This plugin is licensed under the GNU APGL v3+. \ No newline at end of file diff --git a/docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/README.rst b/docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/README.rst new file mode 100644 index 00000000..ce52a8c0 --- /dev/null +++ b/docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/README.rst @@ -0,0 +1,15 @@ +================ + Custom Licenses +================ + +Enable by configuring all custom licenses in the form of: +license_x=Abbreviation, Full Name, URL to license + +Make sure to only insert one line per license without line breaks. + +E.g. do this into mediagoblin_local.ini: +[[mediagoblin_licenses]] +license_1=Chicken Dance, Chicken Dance License v1.0, https://raw.github.com/supertunaman/cdl/f0ae734f4abce311070ac0c401dbc0230cbc4344/COPYING +license_2=WTFPL, Do What the Fuck Public License v2.0, http://sam.zoy.org/wtfpl/ + +This plugin is licensed under the GNU APGL v3+. \ No newline at end of file diff --git a/docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/__init__.py b/docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/__init__.py new file mode 100644 index 00000000..37f5a390 --- /dev/null +++ b/docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/__init__.py @@ -0,0 +1,69 @@ +# GNU MediaGoblin -- federated, autonomous media hosting +# Copyright (C) 2011, 2012 MediaGoblin contributors. See AUTHORS. +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU Affero General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU Affero General Public License for more details. +# +# You should have received a copy of the GNU Affero General Public License +# along with this program. If not, see . +from __future__ import unicode_literals + +import logging +from mediagoblin.tools.pluginapi import get_config +from mediagoblin.tools import licenses + +__VERSION__ = '0.1.2' # releases get numbers, post release a "+" appended +_log = logging.getLogger(__name__) + +SORTED_PLUGIN_LICENSES = [] +"""This is the equivalent of MG.tools.licenses.SORTED_LICENSES +that we want to replace""" + + +class CustomLicenses(object): + _setup_plugin_called = 0 + + @classmethod + def setup_plugin(cls): + if cls._setup_plugin_called: + return # Only set up once + cls._setup_plugin_called += 1 + _log.info('Configurable license plugin setting up!') + # Get configured licenses + config = get_config(cls.__module__) + if not config: + _log.warn('There are no licenses configured at all.') + return # Nothing configured, nothing to do... + + for k,v in config.iteritems(): + if not k.lower().startswith('license_'): + continue + (abbrev, name, url) = config.as_list(k) + _log.info("Adding license: {0}".format(abbrev)) + SORTED_PLUGIN_LICENSES.append(licenses.License(abbrev, name, url)) + + # Set the regular license list to our custom ones: + licenses.SORTED_LICENSES = SORTED_PLUGIN_LICENSES + # create dict {url: License,...} to enable fast license lookup by url. + + # The data structure in + # mediagoblin.tools.licenses.SUPPORTED_LICENSES and SORTED_LICENSES + # is really not optimal. What we want there is a "OrderedDict" that + # can give us order AND quick lookup by key at the same time. But as + # that is python >=2.7 and we have to deal with python 2.6, we'll + # live with the data duplication in 2 structures for now. It's not + # like we are going to have hundreds of licenses, fortunately. + licenses.SUPPORTED_LICENSES = dict(((l.uri, l) for l in \ + SORTED_PLUGIN_LICENSES)) + + +hooks = { + 'setup': CustomLicenses.setup_plugin + } diff --git a/docs/source/build/mediagoblin-licenses/mediagoblin_licenses/README.rst b/docs/source/build/mediagoblin-licenses/mediagoblin_licenses/README.rst new file mode 100644 index 00000000..ce52a8c0 --- /dev/null +++ b/docs/source/build/mediagoblin-licenses/mediagoblin_licenses/README.rst @@ -0,0 +1,15 @@ +================ + Custom Licenses +================ + +Enable by configuring all custom licenses in the form of: +license_x=Abbreviation, Full Name, URL to license + +Make sure to only insert one line per license without line breaks. + +E.g. do this into mediagoblin_local.ini: +[[mediagoblin_licenses]] +license_1=Chicken Dance, Chicken Dance License v1.0, https://raw.github.com/supertunaman/cdl/f0ae734f4abce311070ac0c401dbc0230cbc4344/COPYING +license_2=WTFPL, Do What the Fuck Public License v2.0, http://sam.zoy.org/wtfpl/ + +This plugin is licensed under the GNU APGL v3+. \ No newline at end of file diff --git a/docs/source/build/mediagoblin-licenses/mediagoblin_licenses/__init__.py b/docs/source/build/mediagoblin-licenses/mediagoblin_licenses/__init__.py new file mode 100644 index 00000000..37f5a390 --- /dev/null +++ b/docs/source/build/mediagoblin-licenses/mediagoblin_licenses/__init__.py @@ -0,0 +1,69 @@ +# GNU MediaGoblin -- federated, autonomous media hosting +# Copyright (C) 2011, 2012 MediaGoblin contributors. See AUTHORS. +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU Affero General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU Affero General Public License for more details. +# +# You should have received a copy of the GNU Affero General Public License +# along with this program. If not, see . +from __future__ import unicode_literals + +import logging +from mediagoblin.tools.pluginapi import get_config +from mediagoblin.tools import licenses + +__VERSION__ = '0.1.2' # releases get numbers, post release a "+" appended +_log = logging.getLogger(__name__) + +SORTED_PLUGIN_LICENSES = [] +"""This is the equivalent of MG.tools.licenses.SORTED_LICENSES +that we want to replace""" + + +class CustomLicenses(object): + _setup_plugin_called = 0 + + @classmethod + def setup_plugin(cls): + if cls._setup_plugin_called: + return # Only set up once + cls._setup_plugin_called += 1 + _log.info('Configurable license plugin setting up!') + # Get configured licenses + config = get_config(cls.__module__) + if not config: + _log.warn('There are no licenses configured at all.') + return # Nothing configured, nothing to do... + + for k,v in config.iteritems(): + if not k.lower().startswith('license_'): + continue + (abbrev, name, url) = config.as_list(k) + _log.info("Adding license: {0}".format(abbrev)) + SORTED_PLUGIN_LICENSES.append(licenses.License(abbrev, name, url)) + + # Set the regular license list to our custom ones: + licenses.SORTED_LICENSES = SORTED_PLUGIN_LICENSES + # create dict {url: License,...} to enable fast license lookup by url. + + # The data structure in + # mediagoblin.tools.licenses.SUPPORTED_LICENSES and SORTED_LICENSES + # is really not optimal. What we want there is a "OrderedDict" that + # can give us order AND quick lookup by key at the same time. But as + # that is python >=2.7 and we have to deal with python 2.6, we'll + # live with the data duplication in 2 structures for now. It's not + # like we are going to have hundreds of licenses, fortunately. + licenses.SUPPORTED_LICENSES = dict(((l.uri, l) for l in \ + SORTED_PLUGIN_LICENSES)) + + +hooks = { + 'setup': CustomLicenses.setup_plugin + } diff --git a/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/PKG-INFO b/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/PKG-INFO new file mode 100644 index 00000000..047efe83 --- /dev/null +++ b/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/PKG-INFO @@ -0,0 +1,11 @@ +Metadata-Version: 1.1 +Name: mediagoblin-licenses +Version: 0.1.2 +Summary: Customize the licenses for your mediagoblin installation +Home-page: https://gitorious.org/mediagoblin-licenses/mediagoblin-licenses +Author: Sebastian Spaeth +Author-email: Sebastian@SSpaeth.de +License: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+) +Download-URL: https://gitorious.org/mediagoblin-licenses/mediagoblin-licenses/archive-tarball/mediagoblin-licenses-v0.1.2 +Description: UNKNOWN +Platform: UNKNOWN diff --git a/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/SOURCES.txt b/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/SOURCES.txt new file mode 100644 index 00000000..0e504e97 --- /dev/null +++ b/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/SOURCES.txt @@ -0,0 +1,6 @@ +README +mediagoblin_licenses/__init__.py +pip-egg-info/mediagoblin_licenses.egg-info/PKG-INFO +pip-egg-info/mediagoblin_licenses.egg-info/SOURCES.txt +pip-egg-info/mediagoblin_licenses.egg-info/dependency_links.txt +pip-egg-info/mediagoblin_licenses.egg-info/top_level.txt \ No newline at end of file diff --git a/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/dependency_links.txt b/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/dependency_links.txt new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/dependency_links.txt @@ -0,0 +1 @@ + diff --git a/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/top_level.txt b/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/top_level.txt new file mode 100644 index 00000000..142877ed --- /dev/null +++ b/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/top_level.txt @@ -0,0 +1 @@ +mediagoblin_licenses diff --git a/docs/source/build/mediagoblin-licenses/setup.py b/docs/source/build/mediagoblin-licenses/setup.py new file mode 100644 index 00000000..952ba3ce --- /dev/null +++ b/docs/source/build/mediagoblin-licenses/setup.py @@ -0,0 +1,30 @@ +#!/usr/bin/env python +from distutils.core import setup +import re + +from sys import version +assert version >= '2.6', 'This package requires python 2.6 at least. Sorry.' + +def get_version(): + """Parse __init__.py for version info, we cannot import it""" + version_re = re.compile(r'\s*__VERSION__\s*=\s*("|\')([\w\.\+]+)(\1)') + with open('mediagoblin_licenses/__init__.py', 'rt') as file: + for line in file: + if version_re.match(line): + return version_re.match(line).group(2) +__VERSION__ = get_version() + + +setup(name='mediagoblin-licenses', + version=__VERSION__, + description='Customize the licenses for your mediagoblin installation', + author='Sebastian Spaeth', + author_email='Sebastian@SSpaeth.de', + url='https://gitorious.org/mediagoblin-licenses/mediagoblin-licenses', + download_url='https://gitorious.org/mediagoblin-licenses/mediagoblin-licenses/archive-tarball/mediagoblin-licenses-v' + __VERSION__, + # http://bugs.python.org/issue13943. Must not be unicode... + packages=['mediagoblin_licenses'], + package_data = {'mediagoblin_licenses': ['README.rst', 'COPYING']}, + license=(b'License :: OSI Approved :: GNU Affero General Public License ' + b'v3 or later (AGPLv3+)') + ) diff --git a/docs/source/build/pip-delete-this-directory.txt b/docs/source/build/pip-delete-this-directory.txt new file mode 100644 index 00000000..c8883ea9 --- /dev/null +++ b/docs/source/build/pip-delete-this-directory.txt @@ -0,0 +1,5 @@ +This file is placed here by pip to indicate the source was put +here by pip. + +Once this package is successfully installed this source code will be +deleted (unless you remove this file). diff --git a/docs/source/plugindocs/trim_whitespace.rst b/docs/source/plugindocs/trim_whitespace.rst new file mode 100644 index 00000000..eb38e0e5 --- /dev/null +++ b/docs/source/plugindocs/trim_whitespace.rst @@ -0,0 +1 @@ +.. include:: ../../../mediagoblin/plugins/trim_whitespace/README.rst diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 25d4d83f..9b45f642 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -19,6 +19,15 @@ This chapter has important information for releases in it. If you're upgrading from a previous release, please read it carefully, or at least skim over it. +WIP +===== + +**New features** + +**Other changed** + +* Dependency list has been reduced not requireing the "webob" package anymore. + 0.3.2 ===== -- cgit v1.2.3 From 511d5b89664daef455da0579e8c8658e5b81cce5 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Sat, 22 Dec 2012 12:05:03 +0100 Subject: Revert accidental checkin Commit 8d19cb2445e2aa1f53431da26d866bf9b5e25872 accidentally included my docs/source/build directory. Removing it again. Thanks to Elrond for noticing. Signed-off-by: Sebastian Spaeth --- docs/source/build/mediagoblin-licenses/PKG-INFO | 11 ---- docs/source/build/mediagoblin-licenses/README | 15 ----- .../mediagoblin_licenses/README.rst | 15 ----- .../mediagoblin_licenses/__init__.py | 69 ---------------------- .../mediagoblin_licenses/README.rst | 15 ----- .../mediagoblin_licenses/__init__.py | 69 ---------------------- .../mediagoblin_licenses.egg-info/PKG-INFO | 11 ---- .../mediagoblin_licenses.egg-info/SOURCES.txt | 6 -- .../dependency_links.txt | 1 - .../mediagoblin_licenses.egg-info/top_level.txt | 1 - docs/source/build/mediagoblin-licenses/setup.py | 30 ---------- docs/source/build/pip-delete-this-directory.txt | 5 -- 12 files changed, 248 deletions(-) delete mode 100644 docs/source/build/mediagoblin-licenses/PKG-INFO delete mode 100644 docs/source/build/mediagoblin-licenses/README delete mode 100644 docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/README.rst delete mode 100644 docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/__init__.py delete mode 100644 docs/source/build/mediagoblin-licenses/mediagoblin_licenses/README.rst delete mode 100644 docs/source/build/mediagoblin-licenses/mediagoblin_licenses/__init__.py delete mode 100644 docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/PKG-INFO delete mode 100644 docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/SOURCES.txt delete mode 100644 docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/dependency_links.txt delete mode 100644 docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/top_level.txt delete mode 100644 docs/source/build/mediagoblin-licenses/setup.py delete mode 100644 docs/source/build/pip-delete-this-directory.txt (limited to 'docs/source') diff --git a/docs/source/build/mediagoblin-licenses/PKG-INFO b/docs/source/build/mediagoblin-licenses/PKG-INFO deleted file mode 100644 index 047efe83..00000000 --- a/docs/source/build/mediagoblin-licenses/PKG-INFO +++ /dev/null @@ -1,11 +0,0 @@ -Metadata-Version: 1.1 -Name: mediagoblin-licenses -Version: 0.1.2 -Summary: Customize the licenses for your mediagoblin installation -Home-page: https://gitorious.org/mediagoblin-licenses/mediagoblin-licenses -Author: Sebastian Spaeth -Author-email: Sebastian@SSpaeth.de -License: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+) -Download-URL: https://gitorious.org/mediagoblin-licenses/mediagoblin-licenses/archive-tarball/mediagoblin-licenses-v0.1.2 -Description: UNKNOWN -Platform: UNKNOWN diff --git a/docs/source/build/mediagoblin-licenses/README b/docs/source/build/mediagoblin-licenses/README deleted file mode 100644 index ce52a8c0..00000000 --- a/docs/source/build/mediagoblin-licenses/README +++ /dev/null @@ -1,15 +0,0 @@ -================ - Custom Licenses -================ - -Enable by configuring all custom licenses in the form of: -license_x=Abbreviation, Full Name, URL to license - -Make sure to only insert one line per license without line breaks. - -E.g. do this into mediagoblin_local.ini: -[[mediagoblin_licenses]] -license_1=Chicken Dance, Chicken Dance License v1.0, https://raw.github.com/supertunaman/cdl/f0ae734f4abce311070ac0c401dbc0230cbc4344/COPYING -license_2=WTFPL, Do What the Fuck Public License v2.0, http://sam.zoy.org/wtfpl/ - -This plugin is licensed under the GNU APGL v3+. \ No newline at end of file diff --git a/docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/README.rst b/docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/README.rst deleted file mode 100644 index ce52a8c0..00000000 --- a/docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/README.rst +++ /dev/null @@ -1,15 +0,0 @@ -================ - Custom Licenses -================ - -Enable by configuring all custom licenses in the form of: -license_x=Abbreviation, Full Name, URL to license - -Make sure to only insert one line per license without line breaks. - -E.g. do this into mediagoblin_local.ini: -[[mediagoblin_licenses]] -license_1=Chicken Dance, Chicken Dance License v1.0, https://raw.github.com/supertunaman/cdl/f0ae734f4abce311070ac0c401dbc0230cbc4344/COPYING -license_2=WTFPL, Do What the Fuck Public License v2.0, http://sam.zoy.org/wtfpl/ - -This plugin is licensed under the GNU APGL v3+. \ No newline at end of file diff --git a/docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/__init__.py b/docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/__init__.py deleted file mode 100644 index 37f5a390..00000000 --- a/docs/source/build/mediagoblin-licenses/build/lib.linux-x86_64-2.7/mediagoblin_licenses/__init__.py +++ /dev/null @@ -1,69 +0,0 @@ -# GNU MediaGoblin -- federated, autonomous media hosting -# Copyright (C) 2011, 2012 MediaGoblin contributors. See AUTHORS. -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see . -from __future__ import unicode_literals - -import logging -from mediagoblin.tools.pluginapi import get_config -from mediagoblin.tools import licenses - -__VERSION__ = '0.1.2' # releases get numbers, post release a "+" appended -_log = logging.getLogger(__name__) - -SORTED_PLUGIN_LICENSES = [] -"""This is the equivalent of MG.tools.licenses.SORTED_LICENSES -that we want to replace""" - - -class CustomLicenses(object): - _setup_plugin_called = 0 - - @classmethod - def setup_plugin(cls): - if cls._setup_plugin_called: - return # Only set up once - cls._setup_plugin_called += 1 - _log.info('Configurable license plugin setting up!') - # Get configured licenses - config = get_config(cls.__module__) - if not config: - _log.warn('There are no licenses configured at all.') - return # Nothing configured, nothing to do... - - for k,v in config.iteritems(): - if not k.lower().startswith('license_'): - continue - (abbrev, name, url) = config.as_list(k) - _log.info("Adding license: {0}".format(abbrev)) - SORTED_PLUGIN_LICENSES.append(licenses.License(abbrev, name, url)) - - # Set the regular license list to our custom ones: - licenses.SORTED_LICENSES = SORTED_PLUGIN_LICENSES - # create dict {url: License,...} to enable fast license lookup by url. - - # The data structure in - # mediagoblin.tools.licenses.SUPPORTED_LICENSES and SORTED_LICENSES - # is really not optimal. What we want there is a "OrderedDict" that - # can give us order AND quick lookup by key at the same time. But as - # that is python >=2.7 and we have to deal with python 2.6, we'll - # live with the data duplication in 2 structures for now. It's not - # like we are going to have hundreds of licenses, fortunately. - licenses.SUPPORTED_LICENSES = dict(((l.uri, l) for l in \ - SORTED_PLUGIN_LICENSES)) - - -hooks = { - 'setup': CustomLicenses.setup_plugin - } diff --git a/docs/source/build/mediagoblin-licenses/mediagoblin_licenses/README.rst b/docs/source/build/mediagoblin-licenses/mediagoblin_licenses/README.rst deleted file mode 100644 index ce52a8c0..00000000 --- a/docs/source/build/mediagoblin-licenses/mediagoblin_licenses/README.rst +++ /dev/null @@ -1,15 +0,0 @@ -================ - Custom Licenses -================ - -Enable by configuring all custom licenses in the form of: -license_x=Abbreviation, Full Name, URL to license - -Make sure to only insert one line per license without line breaks. - -E.g. do this into mediagoblin_local.ini: -[[mediagoblin_licenses]] -license_1=Chicken Dance, Chicken Dance License v1.0, https://raw.github.com/supertunaman/cdl/f0ae734f4abce311070ac0c401dbc0230cbc4344/COPYING -license_2=WTFPL, Do What the Fuck Public License v2.0, http://sam.zoy.org/wtfpl/ - -This plugin is licensed under the GNU APGL v3+. \ No newline at end of file diff --git a/docs/source/build/mediagoblin-licenses/mediagoblin_licenses/__init__.py b/docs/source/build/mediagoblin-licenses/mediagoblin_licenses/__init__.py deleted file mode 100644 index 37f5a390..00000000 --- a/docs/source/build/mediagoblin-licenses/mediagoblin_licenses/__init__.py +++ /dev/null @@ -1,69 +0,0 @@ -# GNU MediaGoblin -- federated, autonomous media hosting -# Copyright (C) 2011, 2012 MediaGoblin contributors. See AUTHORS. -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see . -from __future__ import unicode_literals - -import logging -from mediagoblin.tools.pluginapi import get_config -from mediagoblin.tools import licenses - -__VERSION__ = '0.1.2' # releases get numbers, post release a "+" appended -_log = logging.getLogger(__name__) - -SORTED_PLUGIN_LICENSES = [] -"""This is the equivalent of MG.tools.licenses.SORTED_LICENSES -that we want to replace""" - - -class CustomLicenses(object): - _setup_plugin_called = 0 - - @classmethod - def setup_plugin(cls): - if cls._setup_plugin_called: - return # Only set up once - cls._setup_plugin_called += 1 - _log.info('Configurable license plugin setting up!') - # Get configured licenses - config = get_config(cls.__module__) - if not config: - _log.warn('There are no licenses configured at all.') - return # Nothing configured, nothing to do... - - for k,v in config.iteritems(): - if not k.lower().startswith('license_'): - continue - (abbrev, name, url) = config.as_list(k) - _log.info("Adding license: {0}".format(abbrev)) - SORTED_PLUGIN_LICENSES.append(licenses.License(abbrev, name, url)) - - # Set the regular license list to our custom ones: - licenses.SORTED_LICENSES = SORTED_PLUGIN_LICENSES - # create dict {url: License,...} to enable fast license lookup by url. - - # The data structure in - # mediagoblin.tools.licenses.SUPPORTED_LICENSES and SORTED_LICENSES - # is really not optimal. What we want there is a "OrderedDict" that - # can give us order AND quick lookup by key at the same time. But as - # that is python >=2.7 and we have to deal with python 2.6, we'll - # live with the data duplication in 2 structures for now. It's not - # like we are going to have hundreds of licenses, fortunately. - licenses.SUPPORTED_LICENSES = dict(((l.uri, l) for l in \ - SORTED_PLUGIN_LICENSES)) - - -hooks = { - 'setup': CustomLicenses.setup_plugin - } diff --git a/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/PKG-INFO b/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/PKG-INFO deleted file mode 100644 index 047efe83..00000000 --- a/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/PKG-INFO +++ /dev/null @@ -1,11 +0,0 @@ -Metadata-Version: 1.1 -Name: mediagoblin-licenses -Version: 0.1.2 -Summary: Customize the licenses for your mediagoblin installation -Home-page: https://gitorious.org/mediagoblin-licenses/mediagoblin-licenses -Author: Sebastian Spaeth -Author-email: Sebastian@SSpaeth.de -License: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+) -Download-URL: https://gitorious.org/mediagoblin-licenses/mediagoblin-licenses/archive-tarball/mediagoblin-licenses-v0.1.2 -Description: UNKNOWN -Platform: UNKNOWN diff --git a/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/SOURCES.txt b/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/SOURCES.txt deleted file mode 100644 index 0e504e97..00000000 --- a/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/SOURCES.txt +++ /dev/null @@ -1,6 +0,0 @@ -README -mediagoblin_licenses/__init__.py -pip-egg-info/mediagoblin_licenses.egg-info/PKG-INFO -pip-egg-info/mediagoblin_licenses.egg-info/SOURCES.txt -pip-egg-info/mediagoblin_licenses.egg-info/dependency_links.txt -pip-egg-info/mediagoblin_licenses.egg-info/top_level.txt \ No newline at end of file diff --git a/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/dependency_links.txt b/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/dependency_links.txt deleted file mode 100644 index 8b137891..00000000 --- a/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/dependency_links.txt +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/top_level.txt b/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/top_level.txt deleted file mode 100644 index 142877ed..00000000 --- a/docs/source/build/mediagoblin-licenses/pip-egg-info/mediagoblin_licenses.egg-info/top_level.txt +++ /dev/null @@ -1 +0,0 @@ -mediagoblin_licenses diff --git a/docs/source/build/mediagoblin-licenses/setup.py b/docs/source/build/mediagoblin-licenses/setup.py deleted file mode 100644 index 952ba3ce..00000000 --- a/docs/source/build/mediagoblin-licenses/setup.py +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/env python -from distutils.core import setup -import re - -from sys import version -assert version >= '2.6', 'This package requires python 2.6 at least. Sorry.' - -def get_version(): - """Parse __init__.py for version info, we cannot import it""" - version_re = re.compile(r'\s*__VERSION__\s*=\s*("|\')([\w\.\+]+)(\1)') - with open('mediagoblin_licenses/__init__.py', 'rt') as file: - for line in file: - if version_re.match(line): - return version_re.match(line).group(2) -__VERSION__ = get_version() - - -setup(name='mediagoblin-licenses', - version=__VERSION__, - description='Customize the licenses for your mediagoblin installation', - author='Sebastian Spaeth', - author_email='Sebastian@SSpaeth.de', - url='https://gitorious.org/mediagoblin-licenses/mediagoblin-licenses', - download_url='https://gitorious.org/mediagoblin-licenses/mediagoblin-licenses/archive-tarball/mediagoblin-licenses-v' + __VERSION__, - # http://bugs.python.org/issue13943. Must not be unicode... - packages=['mediagoblin_licenses'], - package_data = {'mediagoblin_licenses': ['README.rst', 'COPYING']}, - license=(b'License :: OSI Approved :: GNU Affero General Public License ' - b'v3 or later (AGPLv3+)') - ) diff --git a/docs/source/build/pip-delete-this-directory.txt b/docs/source/build/pip-delete-this-directory.txt deleted file mode 100644 index c8883ea9..00000000 --- a/docs/source/build/pip-delete-this-directory.txt +++ /dev/null @@ -1,5 +0,0 @@ -This file is placed here by pip to indicate the source was put -here by pip. - -Once this package is successfully installed this source code will be -deleted (unless you remove this file). -- cgit v1.2.3 From b0c8328e547288028e7e43f0ceb1fa9f7c8dac4a Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Fri, 30 Nov 2012 10:10:35 +0100 Subject: Move db.sql.models* to db.models* --- docs/source/siteadmin/relnotes.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 9b45f642..7d480d90 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -26,6 +26,9 @@ WIP **Other changed** +* Plugin writers: Internal restructuring led to mediagoblin.db.sql* be + mediagoblin.db.* starting from 0.3.3 + * Dependency list has been reduced not requireing the "webob" package anymore. 0.3.2 -- cgit v1.2.3 From 3a8b18f85b9affca46a433607d7d9ae723380b94 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Fri, 25 Jan 2013 21:43:49 +0100 Subject: Updated video apt-get to not use glob Also changed some literal blocks to code-blocks --- docs/source/siteadmin/media-types.rst | 34 ++++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 8fbce5e4..23d3f3b9 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -71,16 +71,24 @@ Video To enable video, first install gstreamer and the python-gstreamer bindings (as well as whatever gstremaer extensions you want, -good/bad/ugly). On Debianoid systems:: +good/bad/ugly). On Debianoid systems - sudo apt-get install python-gst0.10 gstreamer0.10-plugins-{base,bad,good,ugly} \ +.. code-block:: bash + + sudo apt-get install python-gst0.10 \ + gstreamer0.10-plugins-base \ + gstreamer0.10-plugins-bad \ + gstreamer0.10-plugins-good \ + gstreamer0.10-plugins-ugly \ gstreamer0.10-ffmpeg Add ``mediagoblin.media_types.video`` to the ``media_types`` list in your ``mediagoblin_local.ini`` and restart MediaGoblin. -Run:: +Run + +.. code-block:: bash ./bin/gmg dbupdate @@ -108,7 +116,9 @@ To install these on Debianoid systems, run:: The ``scikits.audiolab`` package you will install in the next step depends on the ``libsndfile1-dev`` package, so we should install it. -On Debianoid systems, run:: +On Debianoid systems, run + +.. code-block:: bash sudo apt-get install libsndfile1-dev @@ -126,7 +136,9 @@ Then install ``scikits.audiolab`` for the spectrograms:: Add ``mediagoblin.media_types.audio`` to the ``media_types`` list in your ``mediagoblin_local.ini`` and restart MediaGoblin. -Run:: +Run + +.. code-block:: bash ./bin/gmg dbupdate @@ -138,7 +150,9 @@ Ascii art To enable ascii art support, first install the `chardet `_ -library, which is necessary for creating thumbnails of ascii art:: +library, which is necessary for creating thumbnails of ascii art + +.. code-block:: bash ./bin/easy_install chardet @@ -152,7 +166,9 @@ the list would look like this:: media_types = mediagoblin.media_types.image, mediagoblin.media_types.ascii -Run:: +Run + +.. code-block:: bash ./bin/gmg dbupdate @@ -171,7 +187,9 @@ is surely not to work prior to Blender 2.5X). Add ``mediagoblin.media_types.stl`` to the ``media_types`` list in your ``mediagoblin_local.ini`` and restart MediaGoblin. -Run:: +Run + +.. code-block:: bash ./bin/gmg dbupdate -- cgit v1.2.3 From 92c597ca1cd0d93df7246eb2f81f84bcb08673ce Mon Sep 17 00:00:00 2001 From: Elrond Date: Sat, 26 Jan 2013 00:12:18 +0100 Subject: Allow doc string extraction and use for pluginapi. Allow us to extract docstrings from our sources using the sphinx.ext.autodoc module. First use: Extract some of the docs for the pluginapi and provide it in a new "Plugin API" section. --- docs/source/conf.py | 2 +- docs/source/index.rst | 1 + docs/source/pluginwriter/api.rst | 23 +++++++++++++++++++++++ 3 files changed, 25 insertions(+), 1 deletion(-) create mode 100644 docs/source/pluginwriter/api.rst (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 4209acc8..8113e247 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -26,7 +26,7 @@ sys.path.insert(0, os.path.abspath(os.path.join('..', '..'))) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] +extensions = ['sphinx.ext.autodoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['source/_templates'] diff --git a/docs/source/index.rst b/docs/source/index.rst index ac8bd110..adaafb59 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -70,6 +70,7 @@ This guide covers writing new GNU MediaGoblin plugins. pluginwriter/foreward pluginwriter/quickstart + pluginwriter/api Indices and tables diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst new file mode 100644 index 00000000..206c8b0b --- /dev/null +++ b/docs/source/pluginwriter/api.rst @@ -0,0 +1,23 @@ +.. MediaGoblin Documentation + + Written in 2013 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + + +========== +Plugin API +========== + +:mod:`pluginapi` Module +----------------------- + +.. automodule:: mediagoblin.tools.pluginapi + :members: get_config, register_routes, register_template_path -- cgit v1.2.3 From b238a95464fae821b9f83ad723eecf3fd43a52d2 Mon Sep 17 00:00:00 2001 From: Elrond Date: Sat, 26 Jan 2013 13:03:54 +0100 Subject: Add Trim whitespace plugin docs. Added the documentation (which was already present in plugindocs/) to the TOC, so it's getting build and linked. --- docs/source/index.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index adaafb59..24cde4e6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -58,6 +58,7 @@ Part 2: Core plugin documentation plugindocs/flatpagesfile plugindocs/sampleplugin plugindocs/oauth + plugindocs/trim_whitespace Part 3: Plugin Writer's Guide -- cgit v1.2.3 From 3214c653dd72605ecacfffe13d1972c2c88506c1 Mon Sep 17 00:00:00 2001 From: Elrond Date: Sat, 26 Jan 2013 19:20:18 +0100 Subject: Docs: Create new area for developers. We need some "Part" for developers. Currently, it's named "Part 4: Developer's Zone". But we should come up with a better name soon. Moved the codebase docs in there for starters. --- docs/source/devel/codebase.rst | 158 +++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 12 ++- docs/source/siteadmin/codebase.rst | 158 ------------------------------------- 3 files changed, 169 insertions(+), 159 deletions(-) create mode 100644 docs/source/devel/codebase.rst delete mode 100644 docs/source/siteadmin/codebase.rst (limited to 'docs/source') diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst new file mode 100644 index 00000000..73e938e7 --- /dev/null +++ b/docs/source/devel/codebase.rst @@ -0,0 +1,158 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +.. _codebase-chapter: + +======================== + Codebase Documentation +======================== + +.. contents:: Sections + :local: + + +This chapter covers the libraries that GNU MediaGoblin uses as well as +various recipes for getting things done. + +.. Note:: + + This chapter is in flux. Clearly there are things here that aren't + documented. If there's something you have questions about, please + ask! + + See `the join page on the website `_ + for where we hang out. + +For more information on how to get started hacking on GNU MediaGoblin, +see `the wiki `_. + + +Software Stack +============== + +* Project infrastructure + + * `Python `_: the language we're using to write + this + + * `Nose `_: + for unit tests + + * `virtualenv `_: for setting up an + isolated environment to keep mediagoblin and related packages + (potentially not required if MediaGoblin is packaged for your + distro) + +* Data storage + + * `SQLAlchemy `_: SQL ORM and database + interaction library for Python. Currently we support sqlite and + postgress as backends. + +* Web application + + * `Paste Deploy `_ and + `Paste Script `_: we'll use this for + configuring and launching the application + + * `werkzeug `_: nice abstraction layer + from HTTP requests, responses and WSGI bits + + * `Beaker `_: for handling sessions and + caching + + * `Jinja2 `_: the templating engine + + * `WTForms `_: for handling, + validation, and abstraction from HTML forms + + * `Celery `_: for task queuing (resizing + images, encoding video, ...) + + * `Babel `_: Used to extract and compile + translations. + + * `Markdown (for python) `_: + implementation of `Markdown `_ + text-to-html tool to make it easy for people to write richtext + comments, descriptions, and etc. + + * `lxml `_: nice xml and html processing for + python. + +* Media processing libraries + + * `Python Imaging Library `_: + used to resize and otherwise convert images for display. + + * `GStreamer `_: (Optional, for + video hosting sites only) Used to transcode video, and in the + future, probably audio too. + + * `chardet `_: (Optional, for + ascii art hosting sites only) Used to make ascii art thumbnails. + +* Front end + + * `JQuery `_: for groovy JavaScript things + + + +What's where +============ + +After you've run checked out mediagoblin and followed the virtualenv +instantiation instructions, you're faced with the following directory +tree:: + + mediagoblin/ + |- mediagoblin/ # source code + | |- tests/ + | |- templates/ + | |- auth/ + | \- submit/ + |- docs/ # documentation + |- devtools/ # some scripts for developer convenience + | + | # the below directories are installed into your virtualenv checkout + | + |- bin/ # scripts + |- develop-eggs/ + |- lib/ # python libraries installed into your virtualenv + |- include/ + |- mediagoblin.egg-info/ + |- parts/ + |- user_dev/ # sessions, etc + + +As you can see, all the code for GNU MediaGoblin is in the +``mediagoblin`` directory. + +Here are some interesting files and what they do: + +:routing.py: maps url paths to views +:views.py: views handle http requests +:models.py: holds the sqlalchemy schemas---these are the data structures + we're working with + +You'll notice that there are several sub-directories: tests, +templates, auth, submit, ... + +``tests`` holds the unit test code. + +``templates`` holds all the templates for the output. + +``auth`` and ``submit`` are modules that enacpsulate authentication +and media item submission. If you look in these directories, you'll +see they have their own ``routing.py``, ``view.py``, and +``models.py`` in addition to some other code. diff --git a/docs/source/index.rst b/docs/source/index.rst index 24cde4e6..576e7af9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -44,7 +44,6 @@ MediaGoblin website. It is written for site administrators. siteadmin/relnotes siteadmin/theming siteadmin/plugins - siteadmin/codebase .. _core-plugin-section: @@ -74,6 +73,17 @@ This guide covers writing new GNU MediaGoblin plugins. pluginwriter/api +Part 4: Developer's Zone +======================== + +This chapter contains various information for developers. + +.. toctree:: + :maxdepth: 1 + + devel/codebase + + Indices and tables ================== diff --git a/docs/source/siteadmin/codebase.rst b/docs/source/siteadmin/codebase.rst deleted file mode 100644 index 73e938e7..00000000 --- a/docs/source/siteadmin/codebase.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - . - -.. _codebase-chapter: - -======================== - Codebase Documentation -======================== - -.. contents:: Sections - :local: - - -This chapter covers the libraries that GNU MediaGoblin uses as well as -various recipes for getting things done. - -.. Note:: - - This chapter is in flux. Clearly there are things here that aren't - documented. If there's something you have questions about, please - ask! - - See `the join page on the website `_ - for where we hang out. - -For more information on how to get started hacking on GNU MediaGoblin, -see `the wiki `_. - - -Software Stack -============== - -* Project infrastructure - - * `Python `_: the language we're using to write - this - - * `Nose `_: - for unit tests - - * `virtualenv `_: for setting up an - isolated environment to keep mediagoblin and related packages - (potentially not required if MediaGoblin is packaged for your - distro) - -* Data storage - - * `SQLAlchemy `_: SQL ORM and database - interaction library for Python. Currently we support sqlite and - postgress as backends. - -* Web application - - * `Paste Deploy `_ and - `Paste Script `_: we'll use this for - configuring and launching the application - - * `werkzeug `_: nice abstraction layer - from HTTP requests, responses and WSGI bits - - * `Beaker `_: for handling sessions and - caching - - * `Jinja2 `_: the templating engine - - * `WTForms `_: for handling, - validation, and abstraction from HTML forms - - * `Celery `_: for task queuing (resizing - images, encoding video, ...) - - * `Babel `_: Used to extract and compile - translations. - - * `Markdown (for python) `_: - implementation of `Markdown `_ - text-to-html tool to make it easy for people to write richtext - comments, descriptions, and etc. - - * `lxml `_: nice xml and html processing for - python. - -* Media processing libraries - - * `Python Imaging Library `_: - used to resize and otherwise convert images for display. - - * `GStreamer `_: (Optional, for - video hosting sites only) Used to transcode video, and in the - future, probably audio too. - - * `chardet `_: (Optional, for - ascii art hosting sites only) Used to make ascii art thumbnails. - -* Front end - - * `JQuery `_: for groovy JavaScript things - - - -What's where -============ - -After you've run checked out mediagoblin and followed the virtualenv -instantiation instructions, you're faced with the following directory -tree:: - - mediagoblin/ - |- mediagoblin/ # source code - | |- tests/ - | |- templates/ - | |- auth/ - | \- submit/ - |- docs/ # documentation - |- devtools/ # some scripts for developer convenience - | - | # the below directories are installed into your virtualenv checkout - | - |- bin/ # scripts - |- develop-eggs/ - |- lib/ # python libraries installed into your virtualenv - |- include/ - |- mediagoblin.egg-info/ - |- parts/ - |- user_dev/ # sessions, etc - - -As you can see, all the code for GNU MediaGoblin is in the -``mediagoblin`` directory. - -Here are some interesting files and what they do: - -:routing.py: maps url paths to views -:views.py: views handle http requests -:models.py: holds the sqlalchemy schemas---these are the data structures - we're working with - -You'll notice that there are several sub-directories: tests, -templates, auth, submit, ... - -``tests`` holds the unit test code. - -``templates`` holds all the templates for the output. - -``auth`` and ``submit`` are modules that enacpsulate authentication -and media item submission. If you look in these directories, you'll -see they have their own ``routing.py``, ``view.py``, and -``models.py`` in addition to some other code. -- cgit v1.2.3 From ae9f0aec381c7f04898f0dde3af322ec876b9651 Mon Sep 17 00:00:00 2001 From: Elrond Date: Sat, 26 Jan 2013 19:21:40 +0100 Subject: Docs: Add a database guide to the plugin docs. Plugin writers will often need to create new tables. So give them some hints, what they need to do and where they might find more info. --- docs/source/index.rst | 1 + docs/source/pluginwriter/database.rst | 111 ++++++++++++++++++++++++++++++++++ 2 files changed, 112 insertions(+) create mode 100644 docs/source/pluginwriter/database.rst (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index 576e7af9..abd891a0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -70,6 +70,7 @@ This guide covers writing new GNU MediaGoblin plugins. pluginwriter/foreward pluginwriter/quickstart + pluginwriter/database pluginwriter/api diff --git a/docs/source/pluginwriter/database.rst b/docs/source/pluginwriter/database.rst new file mode 100644 index 00000000..58edf3a0 --- /dev/null +++ b/docs/source/pluginwriter/database.rst @@ -0,0 +1,111 @@ +.. MediaGoblin Documentation + + Written in 2013 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + + +======== +Database +======== + + +Accessing Existing Data +======================= + +If your plugin wants to access existing data, this is quite +straight forward. Just import the appropiate models and use +the full power of SQLAlchemy. Take a look at the (upcoming) +database section in the Developer's Chapter. + + +Creating new Tables +=================== + +If your plugin needs some new space to store data, you +should create a new table. Please do not modify core +tables. Not doing so might seem inefficient and possibly +is. It will help keep things sane and easier to upgrade +versions later. + +So if you create a new plugin and need new tables, create a +file named ``models.py`` in your plugin directory. You +might take a look at the core's db.models for some ideas. +Here's a simple one: + +.. code-block:: python + + from mediagoblin.db.base import Base + from sqlalchemy import Column, Integer, Unicode, ForeignKey + + class MediaSecurity(Base): + __tablename__ = "yourplugin__media_security" + + # The primary key *and* reference to the main media_entry + media_entry = Column(Integer, ForeignKey('core__media_entries.id'), + primary_key=True) + get_media_entry = relationship("MediaEntry", + backref=backref("security_rating", cascade="all, delete-orphan")) + + rating = Column(Unicode) + + MODELS = [MediaSecurity] + +That's it. + +Some notes: + +* Make sure all your ``__tablename__`` start with your + plugin's name so the tables of various plugins can't + conflict in the database. (Conflicts in python naming are + much easier to fix later). +* Try to get your database design as good as possible in + the first attempt. Changing the database design later, + when people already have data using the old design, is + possible (see next chapter), but it's not easy. + + +Changing the Database Schema Later +================================== + +If your plugin is in use and instances use it to store some +data, changing the database design is a tricky thing. + +1. Make up your mind how the new schema should look like. +2. Change ``models.py`` to contain the new schema. Keep a + copy of the old version around for your personal + reference later. +3. Now make up your mind (possibly using your old and new + ``models.py``) what steps in SQL are needed to convert + the old schema to the new one. + This is called a "migration". +4. Create a file ``migrations.py`` that will contain all + your migrations and add your new migration. + +Take a look at the core's ``db/migrations.py`` for some +good examples on what you might be able to do. Here's a +simple one to add one column: + +.. code-block:: python + + from mediagoblin.db.migration_tools import RegisterMigration, inspect_table + from sqlalchemy import MetaData, Column, Integer + + MIGRATIONS = {} + + @RegisterMigration(1, MIGRATIONS) + def add_license_preference(db): + metadata = MetaData(bind=db.bind) + + security_table = inspect_table(metadata, 'yourplugin__media_security') + + col = Column('security_level', Integer) + col.create(security_table) + db.commit() -- cgit v1.2.3 From f8107ccccc83a7b2aea3adb6f2fe55c45371c080 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Sun, 27 Jan 2013 22:10:47 +0100 Subject: *docs* intersphinx, exception monitoring --- docs/source/conf.py | 3 +- docs/source/siteadmin/production-deployments.rst | 46 ++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 8113e247..0b2bccac 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -26,7 +26,8 @@ sys.path.insert(0, os.path.abspath(os.path.join('..', '..'))) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx'] +intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None)} # Add any paths that contain templates here, relative to this directory. templates_path = ['source/_templates'] diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst index 356fab7f..0ed5ac6a 100644 --- a/docs/source/siteadmin/production-deployments.rst +++ b/docs/source/siteadmin/production-deployments.rst @@ -77,6 +77,52 @@ Modify your existing MediaGoblin and application init scripts, if necessary, to prevent them from starting their own ``celeryd`` processes. +Monitor exceptions +------------------ + +This is an example config using raven_ to report exceptions and +:py:mod:`logging` messages to a sentry_ instance + +.. _raven: http://raven.readthedocs.org/ +.. _sentry: https://github.com/getsentry + +.. code-block:: ini + + [pipeline:main] + pipeline = + errors + raven + routing + + [loggers] + keys = root, sentry + + [handlers] + keys = console, sentry + + [formatters] + keys = generic + + [logger_root] + level = INFO + handlers = console, sentry + + [logger_sentry] + level = WARN + handlers = console + qualname = sentry.errors + propagate = 0 + + [handler_sentry] + class = raven.handlers.logging.SentryHandler + args = ('http://public:secret@example.com/1',) + level = WARNING + formatter = generic + + [filter:raven] + use = egg:raven#raven + dsn = http://71727ea2c69043e4bbcd793bb0115cd4:e9cedccb32d9482d81f99eeca8b1ad30@sentry.talka.tv/3 + .. _init-script: Use an Init Script -- cgit v1.2.3 From 75621003af128969c322d11aff74ec0c425a9ff4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 30 Jan 2013 13:27:40 -0600 Subject: Added register_template_hooks and get_hook_templates to the plugin api auto module documentation. --- docs/source/pluginwriter/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 206c8b0b..f700e161 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -20,4 +20,4 @@ Plugin API ----------------------- .. automodule:: mediagoblin.tools.pluginapi - :members: get_config, register_routes, register_template_path + :members: get_config, register_routes, register_template_path, register_template_hooks, get_hook_templates -- cgit v1.2.3 From cf41e7d7444fb9d19a777a4720d9b00684e6fe7b Mon Sep 17 00:00:00 2001 From: Elrond Date: Thu, 31 Jan 2013 20:57:03 +0100 Subject: Improve formatting for hook template docs. --- docs/source/pluginwriter/api.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index f700e161..42dc3a3d 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -20,4 +20,5 @@ Plugin API ----------------------- .. automodule:: mediagoblin.tools.pluginapi - :members: get_config, register_routes, register_template_path, register_template_hooks, get_hook_templates + :members: get_config, register_routes, register_template_path, + register_template_hooks, get_hook_templates -- cgit v1.2.3 From 37b48053e9f2da3a6e2378874b025ab152f6f614 Mon Sep 17 00:00:00 2001 From: pythonsnake Date: Sun, 10 Feb 2013 14:07:09 +0100 Subject: Fix bug 461 --- docs/source/siteadmin/deploying.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 91406f96..d1300d72 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -282,6 +282,9 @@ this ``nginx.conf`` file should be modeled on the following:: # Change this to update the upload size limit for your users client_max_body_size 8m; + # prevent attacks (someone uploading a .txt file that the browser interprets as an HTML file, etc.) + add_header X-Content-Type-Options nosniff;· + server_name mediagoblin.example.org www.mediagoblin.example.org; access_log /var/log/nginx/mediagoblin.example.access.log; error_log /var/log/nginx/mediagoblin.example.error.log; -- cgit v1.2.3 From a49c741f1141e8b9ff6022ebeddc4ad335fdab8a Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 24 Feb 2013 16:37:39 -0600 Subject: Removing stray character from pythonsnake's doc change and filling comment This commit sponsored by Johannes Knabbe. Thank you! --- docs/source/siteadmin/deploying.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index d1300d72..9b2324ae 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -282,8 +282,9 @@ this ``nginx.conf`` file should be modeled on the following:: # Change this to update the upload size limit for your users client_max_body_size 8m; - # prevent attacks (someone uploading a .txt file that the browser interprets as an HTML file, etc.) - add_header X-Content-Type-Options nosniff;· + # prevent attacks (someone uploading a .txt file that the browser + # interprets as an HTML file, etc.) + add_header X-Content-Type-Options nosniff; server_name mediagoblin.example.org www.mediagoblin.example.org; access_log /var/log/nginx/mediagoblin.example.access.log; -- cgit v1.2.3 From 35f1f75922a106ec54ddd279e2939b3ce82b9332 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Sat, 23 Feb 2013 00:06:52 +0100 Subject: Added raven plugin docs to docs --- docs/source/index.rst | 1 + docs/source/plugindocs/raven.rst | 1 + 2 files changed, 2 insertions(+) create mode 100644 docs/source/plugindocs/raven.rst (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index abd891a0..9124b1c1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -58,6 +58,7 @@ Part 2: Core plugin documentation plugindocs/sampleplugin plugindocs/oauth plugindocs/trim_whitespace + plugindocs/raven Part 3: Plugin Writer's Guide diff --git a/docs/source/plugindocs/raven.rst b/docs/source/plugindocs/raven.rst new file mode 100644 index 00000000..ae96f3f8 --- /dev/null +++ b/docs/source/plugindocs/raven.rst @@ -0,0 +1 @@ +.. include:: ../../../mediagoblin/plugins/raven/README.rst -- cgit v1.2.3 From f3f530286ff576a3120e29f734aff0b7b7fe882c Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Sun, 3 Mar 2013 02:32:03 +0100 Subject: Updated raven plugin - Added wrap_wsgi, celery_setup, celery_logging_setup hooks - Updated raven plugin docs - Updated production considerations docs - Added raven logging setup --- docs/source/plugindocs/raven.rst | 1 + docs/source/siteadmin/production-deployments.rst | 47 +++--------------------- 2 files changed, 7 insertions(+), 41 deletions(-) (limited to 'docs/source') diff --git a/docs/source/plugindocs/raven.rst b/docs/source/plugindocs/raven.rst index ae96f3f8..71e284d0 100644 --- a/docs/source/plugindocs/raven.rst +++ b/docs/source/plugindocs/raven.rst @@ -1 +1,2 @@ +.. _raven-setup: Set up the raven plugin .. include:: ../../../mediagoblin/plugins/raven/README.rst diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst index 0ed5ac6a..3e9431c9 100644 --- a/docs/source/siteadmin/production-deployments.rst +++ b/docs/source/siteadmin/production-deployments.rst @@ -77,51 +77,16 @@ Modify your existing MediaGoblin and application init scripts, if necessary, to prevent them from starting their own ``celeryd`` processes. -Monitor exceptions ------------------- - -This is an example config using raven_ to report exceptions and -:py:mod:`logging` messages to a sentry_ instance - -.. _raven: http://raven.readthedocs.org/ -.. _sentry: https://github.com/getsentry - -.. code-block:: ini - - [pipeline:main] - pipeline = - errors - raven - routing - - [loggers] - keys = root, sentry - - [handlers] - keys = console, sentry - - [formatters] - keys = generic +.. _sentry: - [logger_root] - level = INFO - handlers = console, sentry +Set up sentry to monitor exceptions +----------------------------------- - [logger_sentry] - level = WARN - handlers = console - qualname = sentry.errors - propagate = 0 +We have a plugin for `raven`_ integration, see the ":doc:`/plugindocs/raven`" +documentation. - [handler_sentry] - class = raven.handlers.logging.SentryHandler - args = ('http://public:secret@example.com/1',) - level = WARNING - formatter = generic +.. _`raven`: http://raven.readthedocs.org - [filter:raven] - use = egg:raven#raven - dsn = http://71727ea2c69043e4bbcd793bb0115cd4:e9cedccb32d9482d81f99eeca8b1ad30@sentry.talka.tv/3 .. _init-script: -- cgit v1.2.3 From 43a2f7fe79c78c387804eadf4be9e3e232a1e0df Mon Sep 17 00:00:00 2001 From: Elrond Date: Sat, 9 Mar 2013 14:02:01 +0100 Subject: Revive old "Design Decisions". This brings back the exact version that was removed in 65e7ce634cfecc87ed6f390f9ccf91be513d2eea. --- docs/source/devel/originaldesigndecisions.rst | 329 ++++++++++++++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 330 insertions(+) create mode 100644 docs/source/devel/originaldesigndecisions.rst (limited to 'docs/source') diff --git a/docs/source/devel/originaldesigndecisions.rst b/docs/source/devel/originaldesigndecisions.rst new file mode 100644 index 00000000..afa1e26b --- /dev/null +++ b/docs/source/devel/originaldesigndecisions.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/index.rst b/docs/source/index.rst index 9124b1c1..0ddacb71 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -84,6 +84,7 @@ This chapter contains various information for developers. :maxdepth: 1 devel/codebase + devel/originaldesigndecisions Indices and tables -- cgit v1.2.3 From ed6a0bcd42afa7b1aa42753ba9e9fc090b83eba8 Mon Sep 17 00:00:00 2001 From: Elrond Date: Sat, 9 Mar 2013 14:51:01 +0100 Subject: Change the _original_ design decisions. - Rename the chapter to "Original *". - Fix links. --- docs/source/devel/originaldesigndecisions.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/source') diff --git a/docs/source/devel/originaldesigndecisions.rst b/docs/source/devel/originaldesigndecisions.rst index afa1e26b..7e5278ec 100644 --- a/docs/source/devel/originaldesigndecisions.rst +++ b/docs/source/devel/originaldesigndecisions.rst @@ -1,8 +1,8 @@ -.. _design-decisions-chapter: +.. _original-design-decisions-chapter: -================== - Design Decisions -================== +=========================== + Original Design Decisions +=========================== .. contents:: Sections :local: @@ -31,13 +31,13 @@ Chris and Will on "Why GNU MediaGoblin": really. So what kind of goblin are we thinking about? We're thinking about these goblins: - .. figure:: goblin.png + .. figure:: ../_static/goblin.png :alt: Cute goblin with a beret. *Figure 1: Cute goblin with a beret. llustrated by Chris Webber* - .. figure:: snugglygoblin.png + .. figure:: ../_static/snugglygoblin.png :scale: 50% :alt: Snuggly goblin with a beret. @@ -324,6 +324,6 @@ Chris Webber on "Why copyright assignment?": 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. + Webber. See `the wiki `_ for details. -- cgit v1.2.3 From 8da84493328a029649e146b8e6fcc95011783b8b Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sat, 9 Mar 2013 12:18:36 -0600 Subject: tyop fix in docs, lazyserer.sh->lazyserver.sh This commit sponsored by S J Bennett. Thanks! --- docs/source/siteadmin/production-deployments.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst index 3e9431c9..1a32d95e 100644 --- a/docs/source/siteadmin/production-deployments.rst +++ b/docs/source/siteadmin/production-deployments.rst @@ -52,7 +52,7 @@ as the basis for your script: :: Separate Celery --------------- -While the ``./lazyserer.sh`` configuration provides an efficient way to +While the ``./lazyserver.sh`` configuration provides an efficient way to start using a MediaGoblin instance, it is not suitable for production deployments for several reasons: -- cgit v1.2.3 From 6e2dcbffaf1ed0a8d83a7998796c5faf8980afd3 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 11 Mar 2013 12:34:02 -0500 Subject: 0.3.3 release notes --- docs/source/siteadmin/relnotes.rst | 59 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 57 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 7d480d90..455e7397 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -19,17 +19,72 @@ This chapter has important information for releases in it. If you're upgrading from a previous release, please read it carefully, or at least skim over it. -WIP +0.3.3 ===== +**Do this to upgrade** + +1. Make sure to run ``bin/gmg dbupdate`` after upgrading. +2. OpenStreetMap is now a plugin, so if you want to use it, add the + following to your config file:: + + [plugins] + [[mediagoblin.plugins.geolocation]] + +If you have your own theme, you may need to make some adjustments to +it as some theme related things may have changed in this releae. If +you run into problems, don't hesitate to join #mediagoblin on +irc.freenode.net and we'll try to help. + **New features** +* New dropdown menu for accessing various features. + +* Significantly improved URL generation. Now mediagoblin won't give + up on making a slug if it looks like there will be a duplicate; + it'll try extra hard to generate a meaningful one instead. + + Similarly, linking to an id no longer can possibly conflict with + linking to a slug; /u/username/m/id:35/ is the kind of reference we + now use to linking to entries with ids. However, old links with + entries that linked to ids should work just fine with our migration. + The only urls that might break in this release are ones using colons + or equal signs. + +* New template hooks for plugin authoring. + +* As a demonstration of new template hooks for plugin authoring, + openstreetmap support now moved to a plugin! + +* Method to add icon to collections switched from icon of paperclip to + button with "add to collection" text. + +* Bug where videos often failed to produce a proper thumbnail fixed! + +* Copying around files in mediagoblin now much more efficient, doesn't + waste gobs of memory. + +* Video transcoding now optional for videos that meet certain + criteria. By default, MediaGoblin will now now transcode webm + videos that are smaller in resolution than the mediagoblin defaults, + and mediagoblin can also be configured to allow theora files to not + be transcoded as well. + +* Per-user license preference option; always want your uploads to be + BY-SA and tired of changing that field? You can now set your + license preference in your user settings. + +* Video player now responsive; better for mobile! + **Other changed** * Plugin writers: Internal restructuring led to mediagoblin.db.sql* be mediagoblin.db.* starting from 0.3.3 -* Dependency list has been reduced not requireing the "webob" package anymore. +* Dependency list has been reduced not requiring the "webob" package anymore. + +* And many small fixes/improvements, too numerous to list! + 0.3.2 ===== -- cgit v1.2.3 From a28c6c4c48cf525621d90879449908cd7fe18169 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 11 Mar 2013 13:35:59 -0500 Subject: Minor release note changes, as suggested by Elrond. This commit sponsored by Martin Ansdell-Smith. Thanks! --- docs/source/siteadmin/relnotes.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 455e7397..21067e75 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -32,9 +32,10 @@ carefully, or at least skim over it. [[mediagoblin.plugins.geolocation]] If you have your own theme, you may need to make some adjustments to -it as some theme related things may have changed in this releae. If -you run into problems, don't hesitate to join #mediagoblin on -irc.freenode.net and we'll try to help. +it as some theme related things may have changed in this release. If +you run into problems, don't hesitate to +`contact us `_ +(IRC is often best). **New features** @@ -56,8 +57,8 @@ irc.freenode.net and we'll try to help. * As a demonstration of new template hooks for plugin authoring, openstreetmap support now moved to a plugin! -* Method to add icon to collections switched from icon of paperclip to - button with "add to collection" text. +* Method to add media to collections switched from icon of paperclip + to button with "add to collection" text. * Bug where videos often failed to produce a proper thumbnail fixed! @@ -65,10 +66,10 @@ irc.freenode.net and we'll try to help. waste gobs of memory. * Video transcoding now optional for videos that meet certain - criteria. By default, MediaGoblin will now now transcode webm - videos that are smaller in resolution than the mediagoblin defaults, - and mediagoblin can also be configured to allow theora files to not - be transcoded as well. + criteria. By default, MediaGoblin will now transcode webm videos + that are smaller in resolution than the mediagoblin defaults, and + mediagoblin can also be configured to allow theora files to not be + transcoded as well. * Per-user license preference option; always want your uploads to be BY-SA and tired of changing that field? You can now set your @@ -76,7 +77,7 @@ irc.freenode.net and we'll try to help. * Video player now responsive; better for mobile! -**Other changed** +**Other changes** * Plugin writers: Internal restructuring led to mediagoblin.db.sql* be mediagoblin.db.* starting from 0.3.3 -- cgit v1.2.3 From 70177c1febb9485a02ca46a36d95eff45c14e599 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 11 Mar 2013 15:18:24 -0500 Subject: You can also DELETE accounts now --- docs/source/siteadmin/relnotes.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 21067e75..5931a467 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -77,6 +77,9 @@ you run into problems, don't hesitate to * Video player now responsive; better for mobile! +* You can now delete your account from the user preferences page if + you so wish. + **Other changes** * Plugin writers: Internal restructuring led to mediagoblin.db.sql* be -- cgit v1.2.3 From fda5ea7aaa6b3879a681f5f1b2da2fe41c6e315c Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Tue, 12 Mar 2013 11:49:39 -0500 Subject: "will now" -> "will not" tyop caught by AVRS... fixed, thanks! --- docs/source/siteadmin/relnotes.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 5931a467..84ec09b5 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -62,13 +62,13 @@ you run into problems, don't hesitate to * Bug where videos often failed to produce a proper thumbnail fixed! -* Copying around files in mediagoblin now much more efficient, doesn't +* Copying around files in MediaGoblin now much more efficient, doesn't waste gobs of memory. * Video transcoding now optional for videos that meet certain - criteria. By default, MediaGoblin will now transcode webm videos - that are smaller in resolution than the mediagoblin defaults, and - mediagoblin can also be configured to allow theora files to not be + criteria. By default, MediaGoblin will not transcode webm videos + that are smaller in resolution than the MediaGoblin defaults, and + MediaGoblin can also be configured to allow theora files to not be transcoded as well. * Per-user license preference option; always want your uploads to be -- cgit v1.2.3 From 340100ee997756e5b84a2b3f7615b1682e07bbb5 Mon Sep 17 00:00:00 2001 From: Elrond Date: Sun, 10 Mar 2013 22:33:28 +0100 Subject: Start a storage section. With the workbench stuff in it. --- docs/source/devel/storage.rst | 43 +++++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 44 insertions(+) create mode 100644 docs/source/devel/storage.rst (limited to 'docs/source') diff --git a/docs/source/devel/storage.rst b/docs/source/devel/storage.rst new file mode 100644 index 00000000..52406c4e --- /dev/null +++ b/docs/source/devel/storage.rst @@ -0,0 +1,43 @@ +========= + Storage +========= + + +See for now: http://wiki.mediagoblin.org/Storage + +Things get moved here. + + +The storage systems attached to your app +---------------------------------------- + +Dynamic content: queue_store and public_store +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The workbench +~~~~~~~~~~~~~ + +In addition, there's a "workbench" used during +processing... it's just for temporary files during +processing, and also for making local copies of stuff that +might be on remote storage interfaces while transitionally +moving/converting from the queue_store to the public store. +See the workbench module documentation for more. + +.. automodule:: mediagoblin.tools.workbench + :members: + :show-inheritance: + + +Static assets / staticdirect +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +StorageInterface and implementations +------------------------------------ + +The guts of StorageInterface and friends +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Writing code to store stuff +~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/index.rst b/docs/source/index.rst index 0ddacb71..7f692d57 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -84,6 +84,7 @@ This chapter contains various information for developers. :maxdepth: 1 devel/codebase + devel/storage devel/originaldesigndecisions -- cgit v1.2.3 From f6097b2eac3d436cefd3e17992fa0b448672214a Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 17 Mar 2013 13:53:45 -0500 Subject: Clarification on some original design decisions things. --- docs/source/devel/originaldesigndecisions.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/source') diff --git a/docs/source/devel/originaldesigndecisions.rst b/docs/source/devel/originaldesigndecisions.rst index 7e5278ec..2843870c 100644 --- a/docs/source/devel/originaldesigndecisions.rst +++ b/docs/source/devel/originaldesigndecisions.rst @@ -10,6 +10,10 @@ This chapter talks a bit about design decisions. +Note: This is an outdated document. It's more or less the historical +reasons for a lot of things. That doesn't mean these decisions have +stayed the same or we haven't changed our minds on some things! + Why GNU MediaGoblin? ==================== @@ -157,6 +161,9 @@ Chris Webber on "Why WSGI Minimalism": Why MongoDB =========== +(Note: We don't use MongoDB anymore. This is the original rationale, +however.) + Chris Webber on "Why MongoDB": In case you were wondering, I am not a NOSQL fanboy, I do not go -- cgit v1.2.3 From 6b92dca59d450004d65b4dfb7a81685f8b10ea10 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 17 Mar 2013 14:16:19 -0500 Subject: Better description of the structure of the application --- docs/source/devel/codebase.rst | 41 +++++++++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 10 deletions(-) (limited to 'docs/source') diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst index 73e938e7..5e8cbcc6 100644 --- a/docs/source/devel/codebase.rst +++ b/docs/source/devel/codebase.rst @@ -117,13 +117,27 @@ tree:: mediagoblin/ |- mediagoblin/ # source code - | |- tests/ - | |- templates/ - | |- auth/ - | \- submit/ + | |- db/ # database setup + | |- tools/ # various utilities + | |- init/ # "initialization" tools (arguably should be in tools/) + | |- tests/ # unit tests + | |- templates/ # templates for this application + | |- media_types/ # code for processing, displaying different media + | |- storage/ # different storage backends + | |- gmg_commands/ # command line tools (./bin/gmg) + | |- themes/ # pre-bundled themes + | | + | | # ... some submodules here as well for different sections + | | # of the application... here's just a few + | |- auth/ # authentication (login/registration) code + | |- user_dev/ # user pages (under /u/), including media pages + | \- submit/ # submitting media for processing + | |- docs/ # documentation |- devtools/ # some scripts for developer convenience | + |- user_dev/ # local instance sessions, media, etc + | | # the below directories are installed into your virtualenv checkout | |- bin/ # scripts @@ -131,8 +145,7 @@ tree:: |- lib/ # python libraries installed into your virtualenv |- include/ |- mediagoblin.egg-info/ - |- parts/ - |- user_dev/ # sessions, etc + \- parts/ As you can see, all the code for GNU MediaGoblin is in the @@ -142,8 +155,7 @@ Here are some interesting files and what they do: :routing.py: maps url paths to views :views.py: views handle http requests -:models.py: holds the sqlalchemy schemas---these are the data structures - we're working with +:forms.py: wtforms stuff for this submodule You'll notice that there are several sub-directories: tests, templates, auth, submit, ... @@ -154,5 +166,14 @@ templates, auth, submit, ... ``auth`` and ``submit`` are modules that enacpsulate authentication and media item submission. If you look in these directories, you'll -see they have their own ``routing.py``, ``view.py``, and -``models.py`` in addition to some other code. +see they have their own ``routing.py``, ``view.py``, and forms.py in +addition to some other code. + +You'll also notice that mediagoblin/db/ contains quite a few things, +including the following: + +:models.py: This is where the database is set up +:mixin.py: Certain functions appended to models from here +:migrations.py: When creating a new migration (a change to the + database structure), we put it here + -- cgit v1.2.3 From d40bce85945ab242caa62c1e269f477a6f4ca8b9 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Mon, 18 Mar 2013 08:50:29 -0500 Subject: Point to the Hacking HOWTO --- docs/source/devel/codebase.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst index 5e8cbcc6..98e0c26e 100644 --- a/docs/source/devel/codebase.rst +++ b/docs/source/devel/codebase.rst @@ -34,7 +34,11 @@ various recipes for getting things done. for where we hang out. For more information on how to get started hacking on GNU MediaGoblin, -see `the wiki `_. +see `the wiki `_, and specifically, go +through the +`Hacking HOWTO `_ +which explains generally how to get going with running an instance for +development. Software Stack -- cgit v1.2.3 From 997ef976699b8d10908ee908cb62b9587d023f92 Mon Sep 17 00:00:00 2001 From: Elrond Date: Tue, 19 Mar 2013 18:52:14 +0100 Subject: Improve release notes formatting. The geolocation ini sample needed more indenting and got a nice "code-block:: ini". --- docs/source/siteadmin/relnotes.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 84ec09b5..6962dc5a 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -26,10 +26,12 @@ carefully, or at least skim over it. 1. Make sure to run ``bin/gmg dbupdate`` after upgrading. 2. OpenStreetMap is now a plugin, so if you want to use it, add the - following to your config file:: + following to your config file: - [plugins] - [[mediagoblin.plugins.geolocation]] + .. code-block:: ini + + [plugins] + [[mediagoblin.plugins.geolocation]] If you have your own theme, you may need to make some adjustments to it as some theme related things may have changed in this release. If -- cgit v1.2.3 From 9430b957e43575df73fec2054079cfef2ef589f4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 21 Mar 2013 10:08:09 -0500 Subject: Move description of software stack below description of "What's where" --- docs/source/devel/codebase.rst | 140 ++++++++++++++++++++--------------------- 1 file changed, 70 insertions(+), 70 deletions(-) (limited to 'docs/source') diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst index 98e0c26e..cd46242c 100644 --- a/docs/source/devel/codebase.rst +++ b/docs/source/devel/codebase.rst @@ -41,6 +41,76 @@ which explains generally how to get going with running an instance for development. +What's where +============ + +After you've run checked out mediagoblin and followed the virtualenv +instantiation instructions, you're faced with the following directory +tree:: + + mediagoblin/ + |- mediagoblin/ # source code + | |- db/ # database setup + | |- tools/ # various utilities + | |- init/ # "initialization" tools (arguably should be in tools/) + | |- tests/ # unit tests + | |- templates/ # templates for this application + | |- media_types/ # code for processing, displaying different media + | |- storage/ # different storage backends + | |- gmg_commands/ # command line tools (./bin/gmg) + | |- themes/ # pre-bundled themes + | | + | | # ... some submodules here as well for different sections + | | # of the application... here's just a few + | |- auth/ # authentication (login/registration) code + | |- user_dev/ # user pages (under /u/), including media pages + | \- submit/ # submitting media for processing + | + |- docs/ # documentation + |- devtools/ # some scripts for developer convenience + | + |- user_dev/ # local instance sessions, media, etc + | + | # the below directories are installed into your virtualenv checkout + | + |- bin/ # scripts + |- develop-eggs/ + |- lib/ # python libraries installed into your virtualenv + |- include/ + |- mediagoblin.egg-info/ + \- parts/ + + +As you can see, all the code for GNU MediaGoblin is in the +``mediagoblin`` directory. + +Here are some interesting files and what they do: + +:routing.py: maps url paths to views +:views.py: views handle http requests +:forms.py: wtforms stuff for this submodule + +You'll notice that there are several sub-directories: tests, +templates, auth, submit, ... + +``tests`` holds the unit test code. + +``templates`` holds all the templates for the output. + +``auth`` and ``submit`` are modules that enacpsulate authentication +and media item submission. If you look in these directories, you'll +see they have their own ``routing.py``, ``view.py``, and forms.py in +addition to some other code. + +You'll also notice that mediagoblin/db/ contains quite a few things, +including the following: + +:models.py: This is where the database is set up +:mixin.py: Certain functions appended to models from here +:migrations.py: When creating a new migration (a change to the + database structure), we put it here + + Software Stack ============== @@ -111,73 +181,3 @@ Software Stack * `JQuery `_: for groovy JavaScript things - -What's where -============ - -After you've run checked out mediagoblin and followed the virtualenv -instantiation instructions, you're faced with the following directory -tree:: - - mediagoblin/ - |- mediagoblin/ # source code - | |- db/ # database setup - | |- tools/ # various utilities - | |- init/ # "initialization" tools (arguably should be in tools/) - | |- tests/ # unit tests - | |- templates/ # templates for this application - | |- media_types/ # code for processing, displaying different media - | |- storage/ # different storage backends - | |- gmg_commands/ # command line tools (./bin/gmg) - | |- themes/ # pre-bundled themes - | | - | | # ... some submodules here as well for different sections - | | # of the application... here's just a few - | |- auth/ # authentication (login/registration) code - | |- user_dev/ # user pages (under /u/), including media pages - | \- submit/ # submitting media for processing - | - |- docs/ # documentation - |- devtools/ # some scripts for developer convenience - | - |- user_dev/ # local instance sessions, media, etc - | - | # the below directories are installed into your virtualenv checkout - | - |- bin/ # scripts - |- develop-eggs/ - |- lib/ # python libraries installed into your virtualenv - |- include/ - |- mediagoblin.egg-info/ - \- parts/ - - -As you can see, all the code for GNU MediaGoblin is in the -``mediagoblin`` directory. - -Here are some interesting files and what they do: - -:routing.py: maps url paths to views -:views.py: views handle http requests -:forms.py: wtforms stuff for this submodule - -You'll notice that there are several sub-directories: tests, -templates, auth, submit, ... - -``tests`` holds the unit test code. - -``templates`` holds all the templates for the output. - -``auth`` and ``submit`` are modules that enacpsulate authentication -and media item submission. If you look in these directories, you'll -see they have their own ``routing.py``, ``view.py``, and forms.py in -addition to some other code. - -You'll also notice that mediagoblin/db/ contains quite a few things, -including the following: - -:models.py: This is where the database is set up -:mixin.py: Certain functions appended to models from here -:migrations.py: When creating a new migration (a change to the - database structure), we put it here - -- cgit v1.2.3 From 82a40cc4e145e4fdf5f81d7b6319cf713afa44c1 Mon Sep 17 00:00:00 2001 From: Elrond Date: Tue, 9 Apr 2013 22:39:04 +0200 Subject: Remove the last traces of beaker. There were still some traces of beaker around: - docs: replaced by reference to itsdangerous. - paste configs: Wiped away. - config_spec.ini: wiped. - test_mgoblin_app.ini: also wiped. --- docs/source/devel/codebase.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst index cd46242c..9718a097 100644 --- a/docs/source/devel/codebase.rst +++ b/docs/source/devel/codebase.rst @@ -142,8 +142,8 @@ Software Stack * `werkzeug `_: nice abstraction layer from HTTP requests, responses and WSGI bits - * `Beaker `_: for handling sessions and - caching + * `itsdangerous `_: + for handling sessions * `Jinja2 `_: the templating engine -- cgit v1.2.3 From 71ef20078cc061317eaf42f20bdc905bcce3ab2a Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 10 Apr 2013 10:52:39 -0500 Subject: Adding some help about what to do if flup flakes out on you --- docs/source/siteadmin/deploying.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 9b2324ae..77e60037 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -185,6 +185,11 @@ flup:: ./bin/easy_install flup +(Sometimes this breaks because flup's site is flakey. If it does for +you, try):: + + ./bin/easy_install https://pypi.python.org/pypi/flup/1.0.3.dev-20110405 + This concludes the initial configuration of the development environment. In the future, when you update your codebase, you should also run:: -- cgit v1.2.3 From 36748921c27deb3f8c9d88f9b7a3c368a427d418 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 11 Apr 2013 16:57:11 -0500 Subject: adding callable_runone and callable_runall to the docs --- docs/source/pluginwriter/api.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 42dc3a3d..44ffd6e8 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -21,4 +21,5 @@ Plugin API .. automodule:: mediagoblin.tools.pluginapi :members: get_config, register_routes, register_template_path, - register_template_hooks, get_hook_templates + register_template_hooks, get_hook_templates, + callable_runone, callable_runall -- cgit v1.2.3 From a80ebf3b64dce807d84ab3993984c211f55b47db Mon Sep 17 00:00:00 2001 From: Alon Levy Date: Wed, 27 Mar 2013 12:21:10 +0200 Subject: add pdf media type The new media type supports pdf and a subset of media recognized by libreoffice via unoconv. Every document added goes through: * conversion to pdf with unoconv if not already a pdf * creation of thumbnail and medium sized image, and pdfinfo generates some information (even for unoconv produces docs - should fix this) Poppler (pdftocairo, pdfinfo) is used. http://poppler.freedesktop.org/ A working but uglified pdf.js integration exists, which is enabled by setting pdf.pdf_js=true mediagoblin_local.ini (disabled in mediagoblin.ini) Adds one test to the test_submission test suite, and another separate test_pdf suite. The tests are only run if media_types.pdf.processing.check_prerequisites passes, so the test suite will not require any extra package. TODO: make test suite say 'skipped' in that case instead of just 'ok' Signed-off-by: Alon Levy --- docs/source/siteadmin/media-types.rst | 37 +++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 23d3f3b9..264dc4fc 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -195,3 +195,40 @@ Run You should now be able to upload .obj and .stl files and MediaGoblin will be able to present them to your wide audience of admirers! + +PDF and Document +================ + +To enable the "PDF and Document" support plugin, you need pdftocairo, pdfinfo, +unoconv with headless support. All executables must be on your execution path. + +To install this on Fedora: + +.. code-block:: bash + + sudo yum install -y ppoppler-utils unoconv libreoffice-headless + +pdf.js relies on git submodules, so be sure you have fetched them: + +.. code-block:: bash + + git submodule init + git submodule update + +This feature has been tested on Fedora with: + poppler-utils-0.20.2-9.fc18.x86_64 + unoconv-0.5-2.fc18.noarch + libreoffice-headless-3.6.5.2-8.fc18.x86_64 + +It may work on some earlier versions, but that is not guaranteed. + +Add ``mediagoblin.media_types.pdf`` to the ``media_types`` list in your +``mediagoblin_local.ini`` and restart MediaGoblin. + +Run + +.. code-block:: bash + + ./bin/gmg dbupdate + + -- cgit v1.2.3 From a2d94b0cca36e5e1442dc26f005afb57f2efb7a1 Mon Sep 17 00:00:00 2001 From: nattily pigeonfowl Date: Tue, 16 Apr 2013 15:34:40 -0400 Subject: Transfered information from http://wiki.mediagoblin.org/Storage into docs/source/devel/storage For info check out ticket: issues.mediagoblin.org/ticket/660 --- docs/source/devel/storage.rst | 85 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 79 insertions(+), 6 deletions(-) (limited to 'docs/source') diff --git a/docs/source/devel/storage.rst b/docs/source/devel/storage.rst index 52406c4e..ce89db09 100644 --- a/docs/source/devel/storage.rst +++ b/docs/source/devel/storage.rst @@ -2,18 +2,19 @@ Storage ========= - -See for now: http://wiki.mediagoblin.org/Storage - -Things get moved here. - - The storage systems attached to your app ---------------------------------------- Dynamic content: queue_store and public_store ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Two instances of the StorageInterface come attached to your app. These +are: + ++ **queue_store:** When a user submits a fresh piece of media for their gallery, before the Processing stage, that piece of media sits here in the queue_store. (It's possible that we'll rename this to "private_store" and start storing more non-publicly-stored stuff in the future...). This is a StorageInterface implementation instance. Visitors to your site probably cannot see it... it isn't designed to be seen, anyway. + ++ **public_store:** After your media goes through processing it gets moved to the public store. This is also a StorageInterface implelementation, and is for stuff that's intended to be seen by site visitors. + The workbench ~~~~~~~~~~~~~ @@ -32,6 +33,28 @@ See the workbench module documentation for more. Static assets / staticdirect ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +On top of all that, there is some static media that comes bundled with your +application. This stuff is kept in: + + mediagoblin/static/ + +These files are for mediagoblin base assets. Things like the CSS files, +logos, etc. You can mount these at whatever location is appropriate to you +(see the direct_remote_path option in the config file) so if your users +are keeping their static assets at http://static.mgoblin.example.org/ but +their actual site is at http://mgoblin.example.org/, you need to be able +to get your static files in a where-it's-mounted agnostic way. There's a +"staticdirector" attached to the request object. It's pretty easy to use; +just look at this bit taken from the +mediagoblin/templates/mediagoblin/base.html main template: + + + +see? Not too hard. As expected, if you configured direct_remote_path to be +http://static.mgoblin.example.org/ you'll get back +http://static.mgoblin.example.org/css/extlib/text.css just as you'd +probably expect. StorageInterface and implementations ------------------------------------ @@ -39,5 +62,55 @@ StorageInterface and implementations The guts of StorageInterface and friends ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +So, the StorageInterface! + +So, the public and queue stores both use StorageInterface implementations +... but what does that mean? It's not too hard. + +Open up: + + mediagoblin/storage.py + +In here you'll see a couple of things. First of all, there's the +StorageInterface class. What you'll see is that this is just a very simple +python class. A few of the methods actually implement things, but for the +most part, they don't. What really matters about this class is the +docstrings. Each expected method is documented as to how it should be +constructed. Want to make a new StorageInterface? Simply subclass it. Want +to know how to use the methods of your storage system? Read these docs, +they span all implementations. + +There are a couple of implementations of these classes bundled in +storage.py as well. The most simple of these is BasicFileStorage, which is +also the default storage system used. As expected, this stores files +locally on your machine. + +There's also a CloudFileStorage system. This provides a mapping to +[OpenStack's swift http://swift.openstack.org/] storage system (used by +RackSpace Cloud files and etc). + +Between these two examples you should be able to get a pretty good idea of +how to write your own storage systems, for storing data across your +beowulf cluster of radioactive monkey brains, whatever. + Writing code to store stuff ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +So what does coding for StorageInterface implementations actually look +like? It's pretty simple, really. For one thing, the design is fairly +inspired by [Django's file storage API +https://docs.djangoproject.com/en/dev/ref/files/storage/]... with some +differences. + +Basically, you access files on "file paths", which aren't exactly like +unix file paths, but are close. If you wanted to store a file on a path +like dir1/dir2/filename.jpg you'd actually write that file path like: + +['dir1', 'dir2', 'filename.jpg'] + +This way we can be *sure* that each component is actually a component of +the path that's expected... we do some filename cleaning on each component. + +Your StorageInterface should pass in and out "file like objects". In other +words, they should provide .read() and .write() at minimum, and probably +also .seek() and .close(). -- cgit v1.2.3 From 827f91e603bf706e628e8d2d625d49d79c62e721 Mon Sep 17 00:00:00 2001 From: Alon Levy Date: Wed, 17 Apr 2013 11:23:37 +0300 Subject: update documentation for s/nose/py.test/ Signed-off-by: Alon Levy --- docs/source/devel/codebase.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/devel/codebase.rst b/docs/source/devel/codebase.rst index 9718a097..122a3297 100644 --- a/docs/source/devel/codebase.rst +++ b/docs/source/devel/codebase.rst @@ -119,7 +119,7 @@ Software Stack * `Python `_: the language we're using to write this - * `Nose `_: + * `Py.Test `_: for unit tests * `virtualenv `_: for setting up an -- cgit v1.2.3 From 3606316e9d7cac12ccf9411fb63c60bb1b775eb9 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 17 Apr 2013 07:41:00 -0500 Subject: ppoppler -> poppler tyop fix --- docs/source/siteadmin/media-types.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 264dc4fc..210094b9 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -206,7 +206,7 @@ To install this on Fedora: .. code-block:: bash - sudo yum install -y ppoppler-utils unoconv libreoffice-headless + sudo yum install -y poppler-utils unoconv libreoffice-headless pdf.js relies on git submodules, so be sure you have fetched them: -- cgit v1.2.3 From 4d0191dcb8b43f82bfacc77ed8c92d0d3c573d8a Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 19 Apr 2013 13:22:03 -0500 Subject: A warning about the plugin API being unstable. --- docs/source/pluginwriter/api.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 44ffd6e8..85870d28 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -16,6 +16,15 @@ Plugin API ========== +This documents the general plugin API. + +Please note, at this point OUR PLUGIN HOOKS MAY AND WILL CHANGE. +Authors are encouraged to develop plugins and work with the +MediaGoblin community to keep them up to date, but this API will be a +moving target for a few releases. + +Please check the release notes for updates! + :mod:`pluginapi` Module ----------------------- -- cgit v1.2.3 From 51d5d3aa20b5f2d7dbe9c88e7d8c21db7ea172d1 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 19 Apr 2013 16:29:03 -0500 Subject: changing the things to document in api.rst --- docs/source/pluginwriter/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 85870d28..3a75d455 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -31,4 +31,4 @@ Please check the release notes for updates! .. automodule:: mediagoblin.tools.pluginapi :members: get_config, register_routes, register_template_path, register_template_hooks, get_hook_templates, - callable_runone, callable_runall + hook_handle, hook_runall, hook_transform, -- cgit v1.2.3 From 90e7fc673878d4eb68db41ae49c47fb543a35a87 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 26 Apr 2013 16:13:05 -0500 Subject: word-wrapping the public/queue storage explainations in storage.rst --- docs/source/devel/storage.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/devel/storage.rst b/docs/source/devel/storage.rst index ce89db09..215f9579 100644 --- a/docs/source/devel/storage.rst +++ b/docs/source/devel/storage.rst @@ -11,9 +11,18 @@ Dynamic content: queue_store and public_store Two instances of the StorageInterface come attached to your app. These are: -+ **queue_store:** When a user submits a fresh piece of media for their gallery, before the Processing stage, that piece of media sits here in the queue_store. (It's possible that we'll rename this to "private_store" and start storing more non-publicly-stored stuff in the future...). This is a StorageInterface implementation instance. Visitors to your site probably cannot see it... it isn't designed to be seen, anyway. - -+ **public_store:** After your media goes through processing it gets moved to the public store. This is also a StorageInterface implelementation, and is for stuff that's intended to be seen by site visitors. ++ **queue_store:** When a user submits a fresh piece of media for + their gallery, before the Processing stage, that piece of media sits + here in the queue_store. (It's possible that we'll rename this to + "private_store" and start storing more non-publicly-stored stuff in + the future...). This is a StorageInterface implementation + instance. Visitors to your site probably cannot see it... it isn't + designed to be seen, anyway. + ++ **public_store:** After your media goes through processing it gets + moved to the public store. This is also a StorageInterface + implelementation, and is for stuff that's intended to be seen by + site visitors. The workbench ~~~~~~~~~~~~~ -- cgit v1.2.3 From b835e15319882477e71c7b03db2c1565dd674a96 Mon Sep 17 00:00:00 2001 From: Elrond Date: Tue, 30 Apr 2013 00:24:45 +0200 Subject: Add warning about crypt/itsdangeroussecret.bin. You should not leak that file, really. --- docs/source/pluginwriter/api.rst | 2 +- docs/source/siteadmin/deploying.rst | 14 ++++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 3a75d455..6323f713 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -31,4 +31,4 @@ Please check the release notes for updates! .. automodule:: mediagoblin.tools.pluginapi :members: get_config, register_routes, register_template_path, register_template_hooks, get_hook_templates, - hook_handle, hook_runall, hook_transform, + hook_handle, hook_runall, hook_transform diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 77e60037..f2f71e01 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -345,3 +345,17 @@ Visit the site you've set up in your browser by visiting smaller deployments. However, for larger production deployments with larger processing requirements, see the ":doc:`production-deployments`" documentation. + + +Security Considerations +~~~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: + + The directory ``user_dev/crypto/`` contains some very + sensitive files. + Especially the ``itsdangeroussecret.bin`` is very important + for session security. Make sure not to leak its contents anywhere. + If the contents gets leaked nevertheless, delete your file + and restart the server, so that it creates a new secret key. + All previous sessions will be invalifated then. -- cgit v1.2.3 From a7d2a8924edd010e707e6da17f17bc74f5db2fbd Mon Sep 17 00:00:00 2001 From: Sam Tuke Date: Mon, 6 May 2013 16:19:10 +0200 Subject: Added info about editing mediagoblin.ini Added link to Apache deployment instructions --- docs/source/siteadmin/deploying.rst | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index f2f71e01..fae4afa0 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -205,6 +205,19 @@ update) Deploy MediaGoblin Services --------------------------- +Edit site configuration +~~~~~~~~~~~~~~~~~~~~~~~ + +A few basic properties must be set before MediaGoblin will work. First make a copy of ``mediagoblin.ini`` for editing so the original config file isn't lost:: + + cp mediagoblin.ini mediagoblin_local.ini + +Then: + +Set ``email_sender_address`` to the address you wish to be used as the sender for system-generated emails +Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if you're mediagoblin directory is not the root directory of your vhost. + + Configure MediaGoblin to use the PostgreSQL database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -240,11 +253,11 @@ browser to confirm that the service is operable. .. _webserver-config: -Connect the Webserver to MediaGoblin with FastCGI -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This section describes how to configure MediaGoblin to work via -FastCGI. Our configuration example will use nginx, however, you may +FastCGI and nginx +~~~~~~~~~~~~~~~~~ + +This configuration example will use nginx, however, you may use any webserver of your choice as long as it supports the FastCGI protocol. If you do not already have a web server, consider nginx, as the configuration files may be more clear than the @@ -345,6 +358,12 @@ Visit the site you've set up in your browser by visiting smaller deployments. However, for larger production deployments with larger processing requirements, see the ":doc:`production-deployments`" documentation. + + +Apache +~~~~~~ + +Instructions and scripts for running MediaGoblin on an Apache server can be found on the `MediaGoblin wiki `_. Security Considerations -- cgit v1.2.3 From f65bf8983611b18ec3a6a042404c50b8558529df Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 8 May 2013 10:57:23 -0500 Subject: Documenting plugin configuration This commit sponsored by David Krupicz. Thanks, David! --- docs/source/pluginwriter/api.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 6323f713..df933511 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -32,3 +32,19 @@ Please check the release notes for updates! :members: get_config, register_routes, register_template_path, register_template_hooks, get_hook_templates, hook_handle, hook_runall, hook_transform + +Configuration +------------- + +Your plugin may define its own configuration defaults. + +Simply add to the directory of your plugin a config_spec.ini file. An +example might look like:: + + [plugin_spec] + some_string = string(default="blork") + some_int = integer(default=50) + +This means that when people enable your plugin in their config you'll +be able to provide defaults as well as type validation. + -- cgit v1.2.3 From b312d2cd83dbbfb32adc30c5eb3a9a4cc6ae9295 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Tue, 14 May 2013 16:09:55 -0500 Subject: Added documentation on view specific hooks This commit sponsored by Matthew Woodward. Thank you! --- docs/source/pluginwriter/api.rst | 62 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index df933511..0d5c82d8 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -48,3 +48,65 @@ example might look like:: This means that when people enable your plugin in their config you'll be able to provide defaults as well as type validation. + +Context Hooks +------------- + +View specific hooks ++++++++++++++++++++ + +You can hook up to almost any template called by any specific view +fairly easily. As long as the view directly or indirectly uses the +method ``render_to_response`` you can access the context via a hook +that has a key in the format of the tuple:: + + (view_symbolic_name, view_template_path) + +Where the "view symbolic name" is the same parameter used in +``request.urlgen()`` to look up the test. So say we're wanting to add +something to the context of the user's homepage. We look in +mediagoblin/user_pages/routing.py and see:: + + add_route('mediagoblin.user_pages.user_home', + '/u//', + 'mediagoblin.user_pages.views:user_home') + +Aha! That means that the name is ``mediagoblin.user_pages.user_home``. +Okay, so then we look at the view at the +``mediagoblin.user_pages.views:user_home`` method:: + + @uses_pagination + def user_home(request, page): + # [...] whole bunch of stuff here + return render_to_response( + request, + 'mediagoblin/user_pages/user.html', + {'user': user, + 'user_gallery_url': user_gallery_url, + 'media_entries': media_entries, + 'pagination': pagination}) + +Nice! So the template appears to be +``mediagoblin/user_pages/user.html``. Cool, that means that the key +is:: + + ("mediagoblin.user_pages.views:user_home", + "mediagoblin/user_pages/user.html") + +The context hook uses ``hook_transform()`` so that means that if we're +hooking into it, our hook will both accept one argument, ``context``, +and should return that modified object, like so:: + + def add_to_user_home_context(context): + context['foo'] = 'bar' + return context + + hooks = { + ("mediagoblin.user_pages.views:user_home", + "mediagoblin/user_pages/user.html"): add_to_user_home_context} + + +Global context hook ++++++++++++++++++++ + + -- cgit v1.2.3 From 1344c561a0da28290bab860e7e628998463fca15 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 15 May 2013 10:37:41 -0500 Subject: Adding global context hooks & fixing method names->symbolic view names in docs This commit sponsored by Sheila Miguez. Thanks Sheila! --- docs/source/pluginwriter/api.rst | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 0d5c82d8..b411fa4d 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -73,7 +73,7 @@ mediagoblin/user_pages/routing.py and see:: Aha! That means that the name is ``mediagoblin.user_pages.user_home``. Okay, so then we look at the view at the -``mediagoblin.user_pages.views:user_home`` method:: +``mediagoblin.user_pages.user_home`` method:: @uses_pagination def user_home(request, page): @@ -90,7 +90,7 @@ Nice! So the template appears to be ``mediagoblin/user_pages/user.html``. Cool, that means that the key is:: - ("mediagoblin.user_pages.views:user_home", + ("mediagoblin.user_pages.user_home", "mediagoblin/user_pages/user.html") The context hook uses ``hook_transform()`` so that means that if we're @@ -102,11 +102,26 @@ and should return that modified object, like so:: return context hooks = { - ("mediagoblin.user_pages.views:user_home", + ("mediagoblin.user_pages.user_home", "mediagoblin/user_pages/user.html"): add_to_user_home_context} Global context hook +++++++++++++++++++ +If you need to add something to the context of *every* view, it is not +hard; there are two hooks hook that also uses hook_transform (like the +above) but make available what you are providing to *every* view. +Note that there is a slight, but critical, difference between the two. + +The most general one is the ``'template_global_context'`` hook. This +one is run only once, and is read into the global context... all views +will get access to what are in this dict. + +The slightly more expensive but more powerful one is +``'template_context_prerender'``. This one is not added to the global +context... it is added to the actual context of each individual +template render right before it is run! Because of this you also can +do some powerful and crazy things, such as checking the request object +or other parts of the context before passing them on. -- cgit v1.2.3 From 0553976187a4ec870f944d2d4d17a4951075d2a8 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 15 May 2013 11:10:25 -0500 Subject: Hook->hooks since there's more than one of them :) --- docs/source/pluginwriter/api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index b411fa4d..56aaac77 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -106,8 +106,8 @@ and should return that modified object, like so:: "mediagoblin/user_pages/user.html"): add_to_user_home_context} -Global context hook -+++++++++++++++++++ +Global context hooks +++++++++++++++++++++ If you need to add something to the context of *every* view, it is not hard; there are two hooks hook that also uses hook_transform (like the -- cgit v1.2.3 From 38ebd05d1a759c3a057ab041124c313cf5724dc4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 15 May 2013 11:29:43 -0500 Subject: Simple tyop, view->test... I was writing too many tests at the time :) --- docs/source/pluginwriter/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 56aaac77..5e0568fd 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -63,7 +63,7 @@ that has a key in the format of the tuple:: (view_symbolic_name, view_template_path) Where the "view symbolic name" is the same parameter used in -``request.urlgen()`` to look up the test. So say we're wanting to add +``request.urlgen()`` to look up the view. So say we're wanting to add something to the context of the user's homepage. We look in mediagoblin/user_pages/routing.py and see:: -- cgit v1.2.3 From 041d2fd785f9b3e18f9fd758f91dbfa7715d317c Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 17 May 2013 15:10:34 -0500 Subject: Just word-wrapping the recent changes to the deployment docs. --- docs/source/siteadmin/deploying.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index fae4afa0..9bcc0637 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -208,14 +208,18 @@ Deploy MediaGoblin Services Edit site configuration ~~~~~~~~~~~~~~~~~~~~~~~ -A few basic properties must be set before MediaGoblin will work. First make a copy of ``mediagoblin.ini`` for editing so the original config file isn't lost:: +A few basic properties must be set before MediaGoblin will work. First +make a copy of ``mediagoblin.ini`` for editing so the original config +file isn't lost:: cp mediagoblin.ini mediagoblin_local.ini - -Then: -Set ``email_sender_address`` to the address you wish to be used as the sender for system-generated emails -Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if you're mediagoblin directory is not the root directory of your vhost. +Then: + - Set ``email_sender_address`` to the address you wish to be used as + the sender for system-generated emails + - Edit ``direct_remote_path``, ``base_dir``, and ``base_url`` if + your mediagoblin directory is not the root directory of your + vhost. Configure MediaGoblin to use the PostgreSQL database @@ -363,7 +367,8 @@ Visit the site you've set up in your browser by visiting Apache ~~~~~~ -Instructions and scripts for running MediaGoblin on an Apache server can be found on the `MediaGoblin wiki `_. +Instructions and scripts for running MediaGoblin on an Apache server +can be found on the `MediaGoblin wiki `_. Security Considerations -- cgit v1.2.3 From 8ca51d32b66b96043c8685aac1e478111612c980 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 22 May 2013 16:44:50 -0500 Subject: Move "bits" templates with dashes in them to underscores Moved all references and also added a note to our release notes. This commit sponsored by Juan Rodriguez. Thank you! --- docs/source/siteadmin/relnotes.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 04863ec6..5d342ef1 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -19,6 +19,22 @@ This chapter has important information for releases in it. If you're upgrading from a previous release, please read it carefully, or at least skim over it. +0.4.0 +===== + +**For theme authors** + +If you have your own theme or you have any "user modified templates", +please note the following: + +* mediagoblin/bits/ files above-content.html, body-end.html, + body-start.html now are renamed... they have underscores instead of + dashes in the filenames now :) +* There's a new file: ``mediagoblin/bits/frontpage_welcome.html``. + You can easily customize this to give a welcome page appropriate to + your site. + + 0.3.3 ===== -- cgit v1.2.3 From d6d2c771bdc111cd26186b1bc42b44f2b3197e05 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 16 May 2013 10:38:45 -0500 Subject: Start of ability to have plugins provide static resources! Note I have not tested any of this yet ;) But we're already on our way: - We've got docs - The hook is there Lots to do still though. But, progress! :) This commit sponsored by Laura Arjona Reina. Thanks larjona! --- docs/source/pluginwriter/api.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 5e0568fd..cd06cbc5 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -125,3 +125,22 @@ context... it is added to the actual context of each individual template render right before it is run! Because of this you also can do some powerful and crazy things, such as checking the request object or other parts of the context before passing them on. + + +Adding static resources +----------------------- + +It's possible to add static resources for your plugin. Say your +plugin needs some special javascript and images... how to provide +them? Then how to access them? MediaGoblin has a way! + + +Attaching to the hook ++++++++++++++++++++++ + +First, you need to register your plugin's resources with the hook. +This is pretty easy actually: you just need to provide a function that +passes back a PluginStatic object. + +.. automodule:: mediagoblin.tools.staticdirect + :members: PluginStatic -- cgit v1.2.3 From 505b4b39b8ca7b273294e5d42d278dd1b89960ea Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 22 May 2013 11:51:46 -0500 Subject: Document assetlink and staticdirect usage for plugins. Still a bit to clean up around what the command to be run actually is, since that will likely change. This commit sponsored by David Decker. Thank you! --- docs/source/pluginwriter/api.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index cd06cbc5..1cfd65d7 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -144,3 +144,34 @@ passes back a PluginStatic object. .. automodule:: mediagoblin.tools.staticdirect :members: PluginStatic + + +Running plugin assetlink +++++++++++++++++++++++++ + +.. TODO: Fix this command when it lands elsewhere ;) + +In order for your plugin assets to be properly served by MediaGoblin, +your plugin's asset directory needs to be symlinked into the directory +that plugin assets are served from. To set this up, run:: + + ./bin/gmg theme assetlink + + +Using staticdirect +++++++++++++++++++ + +Once you have this, you will want to be able to of course link to your +assets! MediaGoblin has a "staticdirect" tool; you want to use this +like so in your templates:: + + staticdirect("css/monkeys.css", "mystaticname") + +Replace "mystaticname" with the name you passed to PluginStatic. The +staticdirect method is, for convenience, attached to the request +object, so you can access this in your templates like: + +.. code-block:: html + + A funny bunny -- cgit v1.2.3 From 24ede04415df1a79da83e2716ab3c714e2080563 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 23 May 2013 13:43:04 -0500 Subject: Documentation changes to reflect new plugin assetlink stuff - updated old theme assetlink section to reflect new location of ./bin/gmg assetlink and removed comment about the plugin command being temporary. - Added a new section to the standard config file on where to put the plugin_static section - Added release notes about said section This commit sponsored by Thomas Webber. Thanks, Dad! --- docs/source/pluginwriter/api.rst | 4 +--- docs/source/siteadmin/deploying.rst | 5 +++++ docs/source/siteadmin/relnotes.rst | 17 +++++++++++++++++ docs/source/siteadmin/theming.rst | 2 +- 4 files changed, 24 insertions(+), 4 deletions(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 1cfd65d7..06295c77 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -149,13 +149,11 @@ passes back a PluginStatic object. Running plugin assetlink ++++++++++++++++++++++++ -.. TODO: Fix this command when it lands elsewhere ;) - In order for your plugin assets to be properly served by MediaGoblin, your plugin's asset directory needs to be symlinked into the directory that plugin assets are served from. To set this up, run:: - ./bin/gmg theme assetlink + ./bin/gmg assetlink Using staticdirect diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 9bcc0637..0ee6b5b4 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -327,6 +327,11 @@ this ``nginx.conf`` file should be modeled on the following:: alias /srv/mediagoblin.example.org/mediagoblin/user_dev/theme_static/; } + # Plugin static files (usually symlinked in) + location /plugin_static/ { + alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/; + } + # Mounting MediaGoblin itself via FastCGI. location / { fastcgi_pass 127.0.0.1:26543; diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 5d342ef1..d25771d3 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -22,6 +22,21 @@ carefully, or at least skim over it. 0.4.0 ===== +**Do this to upgrade** +1. Make sure to run ``bin/gmg dbupdate`` after upgrading. +2. See "For Theme authors" if you have a custom theme. +3. Note that ``./bin/gmg theme assetlink`` is now just + ``./bin/gmg assetlink`` and covers both plugins and assets. + Keep on reading to hear more about new plugin features. +4. If you want to take advantage of new plugins that have statically + served assets, you are going to need to add the new "plugin_static" + section to your nginx config. Basically the following for nginx:: + + # Plugin static files (usually symlinked in) + location /plugin_static/ { + alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/; + } + **For theme authors** If you have your own theme or you have any "user modified templates", @@ -34,6 +49,8 @@ please note the following: You can easily customize this to give a welcome page appropriate to your site. +**New features** + 0.3.3 ===== diff --git a/docs/source/siteadmin/theming.rst b/docs/source/siteadmin/theming.rst index 98ec6de7..11ae3875 100644 --- a/docs/source/siteadmin/theming.rst +++ b/docs/source/siteadmin/theming.rst @@ -51,7 +51,7 @@ want to install this theme! Don't worry, it's fairly painless. 5. Link the assets so that they can be served by your web server:: - $ ./bin/gmg theme assetlink + $ ./bin/gmg assetlink .. Note:: -- cgit v1.2.3 From 5de402781f9b5e9f4167d7d0d565e0c3ec8c4451 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Thu, 23 May 2013 15:56:07 -0500 Subject: Moving statcdirect automodule doc reference to autoclass per Elrond's suggestion. Cleaner! --- docs/source/pluginwriter/api.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 06295c77..44411965 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -142,8 +142,7 @@ First, you need to register your plugin's resources with the hook. This is pretty easy actually: you just need to provide a function that passes back a PluginStatic object. -.. automodule:: mediagoblin.tools.staticdirect - :members: PluginStatic +.. autoclass:: mediagoblin.tools.staticdirect.PluginStatic Running plugin assetlink -- cgit v1.2.3 From 5471e08e7eb27872d7a656ed87911be307dd8290 Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Fri, 24 May 2013 23:07:09 +0200 Subject: Improved docs - Fixed an outdated URL - Rewrote "Separate Celery" section - Changed literal blocks to bash code-blocks - Changed wording when referring to the MediaGoblin WSGI application --- docs/source/siteadmin/production-deployments.rst | 64 +++++++++++++++--------- 1 file changed, 39 insertions(+), 25 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/production-deployments.rst b/docs/source/siteadmin/production-deployments.rst index 1a32d95e..839d3ce5 100644 --- a/docs/source/siteadmin/production-deployments.rst +++ b/docs/source/siteadmin/production-deployments.rst @@ -22,12 +22,14 @@ MediaGoblin in actual production environments. Consider Deploy with Paste ----------------- -The instance configured with ``./lazyserver.sh`` is not ideal for a -production MediaGoblin deployment. Ideally, you should be able to use -an "init" or "control" script to launch and restart the MediaGoblin +The MediaGoblin WSGI application instance you get with ``./lazyserver.sh`` is +not ideal for a production MediaGoblin deployment. Ideally, you should be able +to use an "init" or "control" script to launch and restart the MediaGoblin process. -Use the following command as the basis for such a script: :: +Use the following command as the basis for such a script: + +.. code-block:: bash CELERY_ALWAYS_EAGER=true \ /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ @@ -41,7 +43,9 @@ synchronously, and the user will advance to the next page only after processing is complete. If we take Celery out of "always eager mode," the user will be able to immediately return to the MediaGoblin site while processing is ongoing. In these cases, use the following command -as the basis for your script: :: +as the basis for your script: + +.. code-block:: bash CELERY_ALWAYS_EAGER=false \ /srv/mediagoblin.example.org/mediagoblin/bin/paster serve \ @@ -52,30 +56,40 @@ as the basis for your script: :: Separate Celery --------------- -While the ``./lazyserver.sh`` configuration provides an efficient way to -start using a MediaGoblin instance, it is not suitable for production -deployments for several reasons: +MediaGoblin uses `Celery`_ to handle heavy and long-running tasks. Celery can +be launched in two ways: + +1. Embedded in the MediaGoblin WSGI application [#f-mediagoblin-wsgi-app]_. + This is the way ``./lazyserver.sh`` does it for you. It's simple as you + only have to run one process. The only bad thing with this is that the + heavy and long-running tasks will run *in* the webserver, keeping the user + waiting each time some heavy lifting is needed as in for example processing + a video. This could lead to problems as an aborted connection will halt any + processing and since most front-end web servers *will* terminate your + connection if it doesn't get any response from the MediaGoblin WSGI + application in a while. + +2. As a separate process communicating with the MediaGoblin WSGI application + via a `broker`_. This offloads the heavy lifting from the MediaGoblin WSGI + application and users will be able to continue to browse the site while the + media is being processed in the background. + +.. _`broker`: http://docs.celeryproject.org/en/latest/getting-started/brokers/ +.. _`celery`: http://www.celeryproject.org/ + -In nearly every scenario, work on the Celery queue will need to -balance with the demands of other processes, and cannot proceed -synchronously. This is a particularly relevant problem if you use -MediaGoblin to host video content. Processing with Celery ought to be -operationally separate from the MediaGoblin application itself, this -simplifies management and support better workload distribution. +.. [#f-mediagoblin-wsgi-app] The MediaGoblin WSGI application is the part that + of MediaGoblin that processes HTTP requests. -Basically, if you're doing anything beyond a trivial workload, such as -image hosting for a small set of users, or have limited media types -such as "ASCII art" or icon sharing, you will need to run ``celeryd`` -as a separate process. +To launch Celery separately from the MediaGoblin WSGI application: -Build an :ref:`init script ` around the following -command:: +1. Make sure that the ``CELERY_ALWAYS_EAGER`` environment variable is unset or + set to ``false`` when launching the MediaGoblin WSGI application. +2. Start the ``celeryd`` main process with - CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd + .. code-block:: bash -Modify your existing MediaGoblin and application init scripts, if -necessary, to prevent them from starting their own ``celeryd`` -processes. + CELERY_CONFIG_MODULE=mediagoblin.init.celery.from_celery ./bin/celeryd .. _sentry: @@ -102,7 +116,7 @@ These are scripts provided by the MediaGoblin community: Debian * `GNU MediaGoblin init scripts - `_ + `_ by `Joar Wandborg `_ Arch Linux -- cgit v1.2.3 From d861ffc9ad5118f251fa669028bf774d98b0b451 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 14:10:07 -0500 Subject: Link to the plugin api stuff and the database plugin sections from the quickstart. This commit sponsored by Nathan Stephenson. Thank you! --- docs/source/pluginwriter/api.rst | 1 + docs/source/pluginwriter/database.rst | 9 ++++++--- docs/source/pluginwriter/quickstart.rst | 6 ++++-- 3 files changed, 11 insertions(+), 5 deletions(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 44411965..dc6bcc98 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -11,6 +11,7 @@ Dedication along with this software. If not, see . +.. _plugin-api-chapter: ========== Plugin API diff --git a/docs/source/pluginwriter/database.rst b/docs/source/pluginwriter/database.rst index 58edf3a0..603a19eb 100644 --- a/docs/source/pluginwriter/database.rst +++ b/docs/source/pluginwriter/database.rst @@ -12,9 +12,12 @@ . -======== -Database -======== +.. _plugin-database-chapter: + + +=========================== +Database models for plugins +=========================== Accessing Existing Data diff --git a/docs/source/pluginwriter/quickstart.rst b/docs/source/pluginwriter/quickstart.rst index b5a63f79..6d45ea36 100644 --- a/docs/source/pluginwriter/quickstart.rst +++ b/docs/source/pluginwriter/quickstart.rst @@ -178,8 +178,10 @@ That's it for the quick start! Where to go from here ===================== -See the documentation on the plugin API for code samples and other -things you can use when building your plugin. +See the documentation on the :ref:`plugin-api-chapter` for code +samples and other things you can use when building your plugin. If +your plugin needs its own database models, see +:ref:`plugin-database-chapter`. See `Hitchhiker's Guide to Packaging `_ for more information on -- cgit v1.2.3 From b21220e931e80fa9005f71c026eaa66f5ea225f4 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 14:13:12 -0500 Subject: Actually link to the release notes when we say "see the release notes". This commit sponsored by Brian Kemp. Thank you! --- docs/source/pluginwriter/api.rst | 2 +- docs/source/siteadmin/relnotes.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index dc6bcc98..819fac2d 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -24,7 +24,7 @@ Authors are encouraged to develop plugins and work with the MediaGoblin community to keep them up to date, but this API will be a moving target for a few releases. -Please check the release notes for updates! +Please check the :ref:`release-notes` for updates! :mod:`pluginapi` Module ----------------------- diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index d25771d3..9c9d311c 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -11,6 +11,8 @@ Dedication along with this software. If not, see . +.. _release-notes: + ============= Release Notes ============= -- cgit v1.2.3 From 8ae5d20f197291a1cd2e211e4e5d5ede92718f52 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 15:35:37 -0500 Subject: Where do you find hooks? How do you add them? An explaination! This commit about talking to community members sponsored by community member Aeva Palecek. Thanks! --- docs/source/pluginwriter/api.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 819fac2d..33bb70c4 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -26,6 +26,26 @@ moving target for a few releases. Please check the :ref:`release-notes` for updates! + +How are hooks added? Where do I find them? +------------------------------------------- + +Much of this document talks about hooks, both as in terms of regular +hooks and template hooks. But where do they come from, and how can +you find a list of them? + +For the moment, the best way to find available hooks is to check the +source code itself. (Yes, we should start a more official hook +listing with descriptions soon.) But many hooks you may need do not +exist yet: what to do then? + +The plan at present is that we are adding hooks as people need them, +with community discussion. If you find that you need a hook and +MediaGoblin at present doesn't provide it at present, please +`http://mediagoblin.org/pages/join.html `_! We'll +evaluate what to do from there. + + :mod:`pluginapi` Module ----------------------- -- cgit v1.2.3 From baf2c1c96ec4dbcbb74518852ffdf516d670347c Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 15:57:58 -0500 Subject: Additional hook tips! Documentation on how to modify a wtforms form. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit sponsored by Gian-Maria Daffré. Thank you! --- docs/source/pluginwriter/api.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 33bb70c4..2a7f3c2d 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -193,3 +193,36 @@ object, so you can access this in your templates like: A funny bunny + + +Additional hook tips +-------------------- + +This section aims to explain some tips in regards to adding hooks to +the MediaGoblin repository. + +WTForms hooks +============= + +We haven't totally settled on a way to tranform wtforms form objects, +but here's one way. In your view:: + + from mediagoblin.foo.forms import SomeForm + + def some_view(request) + form_class = hook_transform('some_form_transform', SomeForm) + form = form_class(request.form) + +Then to hook into this form, do something in your plugin like:: + + import wtforms + + class SomeFormAdditions(wtforms.Form): + new_datefield = wtforms.DateField() + + def transform_some_form(orig_form): + class ModifiedForm(orig_form, SomeFormAdditions) + return ModifiedForm + + hooks = { + 'some_form_transform': transform_some_form} -- cgit v1.2.3 From 40019095748fef60ad08d10cbe69437f20d63735 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 16:12:24 -0500 Subject: Actually use the right underlining for the wtforms hooks section --- docs/source/pluginwriter/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 2a7f3c2d..e5ac8df5 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -202,7 +202,7 @@ This section aims to explain some tips in regards to adding hooks to the MediaGoblin repository. WTForms hooks -============= ++++++++++++++ We haven't totally settled on a way to tranform wtforms form objects, but here's one way. In your view:: -- cgit v1.2.3 From 9d881aeeb4df2e9f02c4c1fea7d6435273081fdb Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 17:21:15 -0500 Subject: Provide a tip on how to do interfaces via our plugin API. Uses a frogputer science approach to frobbing as an example (which is total nonsense, but fun). This commit sponsored by Ryan Kelln. Thank you! --- docs/source/pluginwriter/api.rst | 66 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index e5ac8df5..3bb5f445 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -226,3 +226,69 @@ Then to hook into this form, do something in your plugin like:: hooks = { 'some_form_transform': transform_some_form} + + +Interfaces +++++++++++ + +If you want to add a pseudo-interface, it's not difficult to do so. +Just write the interface like so:: + + class FrobInterface(object): + """ + Interface for Frobbing. + + Classes implementing this interface should provide defrob and frob. + They may also implement double_frob, but it is not required; if + not provided, we will use a general technique. + """ + + def defrob(self, frobbed_obj): + """ + Take a frobbed_obj and defrob it. Returns the defrobbed object. + """ + raise NotImplementedError() + + def frob(self, normal_obj): + """ + Take a normal object and frob it. Returns the frobbed object. + """ + raise NotImplementedError() + + def double_frob(self, normal_obj): + """ + Frob this object and return it multiplied by two. + """ + return self.frob(normal_obj) * 2 + + + def some_frob_using_method(): + # something something something + frobber = hook_handle(FrobInterface) + frobber.frob(blah) + + # alternately you could have a default + frobber = hook_handle(FrobInterface) or DefaultFrobber + frobber.defrob(foo) + + +It's fine to use your interface as the key instead of a string if you +like. + +Then a plugin providing your interface can be like:: + + from mediagoblin.foo.frobfrogs import FrobInterface + from frogfrobber import utils + + class FrogFrobber(FrobInterface): + """ + Takes a frogputer science approach to frobbing. + """ + def defrob(self, frobbed_obj): + return utils.frog_defrob(frobbed_obj) + + def frob(self, normal_obj): + return utils.frog_frob(normal_obj) + + hooks = { + FrobInterface: lambda: return FrogFrobber} -- cgit v1.2.3 From ea49f37821410e4b46179853965cd9ac4f2b9688 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Wed, 29 May 2013 18:10:09 -0500 Subject: Explained more clearly why it's okay for interface classes to be keys. This commit sponsored by Nick Glynn. Thank you! --- docs/source/pluginwriter/api.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/pluginwriter/api.rst b/docs/source/pluginwriter/api.rst index 3bb5f445..66def173 100644 --- a/docs/source/pluginwriter/api.rst +++ b/docs/source/pluginwriter/api.rst @@ -273,7 +273,9 @@ Just write the interface like so:: It's fine to use your interface as the key instead of a string if you -like. +like. (Usually this is messy, but since interfaces are public and +since you need to import them into your plugin anyway, interfaces +might as well be keys.) Then a plugin providing your interface can be like:: -- cgit v1.2.3 From 25aad338d4921ec76484c6d2af5e40c97904917d Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Fri, 7 Jun 2013 11:45:07 -0500 Subject: Added some test-writing docs for plugins, but not sure if they're good. ;) This commit sponsored by Joe Lee. Thank you! --- docs/source/index.rst | 1 + docs/source/pluginwriter/tests.rst | 64 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 docs/source/pluginwriter/tests.rst (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index 7f692d57..d71f39f8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -73,6 +73,7 @@ This guide covers writing new GNU MediaGoblin plugins. pluginwriter/quickstart pluginwriter/database pluginwriter/api + pluginwriter/tests Part 4: Developer's Zone diff --git a/docs/source/pluginwriter/tests.rst b/docs/source/pluginwriter/tests.rst new file mode 100644 index 00000000..fe99688f --- /dev/null +++ b/docs/source/pluginwriter/tests.rst @@ -0,0 +1,64 @@ +.. MediaGoblin Documentation + + Written in 2013 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +============================== +Writing unit tests for plugins +============================== + +Here's a brief guide to writing unit tests for plugins. However, it +isn't really ideal. It also hasn't been well tested... yes, there's +some irony there :) + +Some notes: we're using py.test and webtest for unit testing stuff. +Keep that in mind. + +My suggestion is to mime the behavior of `mediagoblin/tests/` and put +that in your own plugin, like `myplugin/tests/`. Copy over +`conftest.py` and `pytest.ini` to your tests directory, but possibly +change the `test_app` fixture to match your own tests' config needs. +For example:: + + import pkg_resources + # [...] + + @pytest.fixture() + def test_app(request): + return get_app( + request, + mgoblin_config=pkg_resources.resource_filename( + 'myplugin.tests', 'myplugin_mediagoblin.ini')) + +In any test module in your tests directory you can then do:: + + def test_somethingorother(test_app): + # real code goes here + pass + +And you'll get a mediagoblin application wrapped in webtest passed in +to your environment. + +If your plugin needs to define multiple configuration setups, you can +actually set up multiple fixtures very easily for this. You can just +set up multiple fixtures with different names that point to different +configs and pass them in as that named argument. + +To run the tests, from mediagoblin's directory (make sure that your +plugin has been added to your mediagoblin checkout's virtualenv!) do:: + + ./runtests.sh /path/to/myplugin/tests/ + +replacing `/path/to/myplugin/` with the actual path to your plugin. + +NOTE: again, the above is untested, but it should probably work. If +you run into trouble, `contact us +`_, preferably on IRC! -- cgit v1.2.3 From 376dcbb493a31e8af4de4ba05c70b17900af04e1 Mon Sep 17 00:00:00 2001 From: Alon Levy Date: Wed, 12 Jun 2013 22:42:58 -0400 Subject: media-types.rst: clarify the pdf media type requirements Explain that it works fine without libreoffice, just with reduced functionality. Signed-off-by: Alon Levy --- docs/source/siteadmin/media-types.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index 210094b9..1527bc70 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -199,8 +199,16 @@ will be able to present them to your wide audience of admirers! PDF and Document ================ -To enable the "PDF and Document" support plugin, you need pdftocairo, pdfinfo, -unoconv with headless support. All executables must be on your execution path. +To enable the "PDF and Document" support plugin, you need: + +1. pdftocairo and pdfinfo for pdf only support. + +2. unoconv with headless support to support converting libreoffice supported + documents as well, such as doc/ppt/xls/odf/odg/odp and more. + For the full list see mediagoblin/media_types/pdf/processing.py, + unoconv_supported. + +All executables must be on your execution path. To install this on Fedora: @@ -208,6 +216,9 @@ To install this on Fedora: sudo yum install -y poppler-utils unoconv libreoffice-headless +Note: You can leave out unoconv and libreoffice-headless if you want only pdf +support. This will result in a much smaller list of dependencies. + pdf.js relies on git submodules, so be sure you have fetched them: .. code-block:: bash -- cgit v1.2.3 From 51702d5b7d4f27fc5131f638269f7e7344a382b0 Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 16 Jun 2013 19:39:03 -0500 Subject: Documenting most of the the many new features in the release notes. --- docs/source/siteadmin/relnotes.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'docs/source') diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 9c9d311c..7b6d8353 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -39,6 +39,13 @@ carefully, or at least skim over it. alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/; } + Similarly, if you've got a modified paste config, you may want to + borrow the app:plugin_static section from the default paste.ini + file. +5. We now use itsdangerous for sessions; if you had any references to + beaker in your paste config you can remove them. Again, see the + default paste.ini config + **For theme authors** If you have your own theme or you have any "user modified templates", @@ -51,7 +58,23 @@ please note the following: You can easily customize this to give a welcome page appropriate to your site. + **New features** +* PDF media type! +* Improved plugin system. More flexible, better documented, with a + new plugin authoring section of the docs. +* itsdangerous based sessions. No more beaker! +* New, experimental Piwigo-based API. This means you should be able + to use MediaGoblin with something like Shotwell. (Again, a word of + caution: this is *very experimental*!) +* Human readable timestamps, and the option to display the original + date of an image when available (available as the + "original_date_visible" variable) +* Moved unit testing system from nosetests to py.test so we can better + handle issues with sqlalchemy exploding with different database + configurations. Long story :) +* You can now disable the ability to post comments. +* Tags now can be up to length 255 characters by default. 0.3.3 -- cgit v1.2.3