From: Christopher Allan Webber <cwebber@dustycloud.org>
Date: Sat, 14 Jul 2012 20:54:14 +0000 (-0500)
Subject: Fleshing out theming documentation; wrote out "structure of things" section
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=e6aaaa96193b20d805c82214debd5a2cd8855efd;p=mediagoblin.git

Fleshing out theming documentation; wrote out "structure of things" section
---

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
+---------------
+
+