heckyel/mediagoblin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Tweak theming docs

Browse Source 
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.
This commit is contained in:
Will Kahn-Greene 2012-07-26 21:33:25 -04:00
parent a04c07376d
commit 4d1761d22f
1 changed files with 55 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
docs/source/siteadmin/theming.rst
View File

@ -17,42 +17,45 @@
Theming MediaGoblin 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 course, you might want something different! Maybe you want something
more light and colorful, or maybe you want something specifically more light and colorful, or maybe you want something specifically
tailored to your organization. Have no fear, MediaGoblin has theming tailored to your organization. Have no fear---MediaGoblin has theming
support! This guide should walk you through installing and making themes. support! This guide should walk you through installing and making
themes.
Installing a theme Installing a theme
================== ==================
.. _theming-installing-section:
Installing the archive Installing the archive
---------------------- ----------------------
Say you have a theme archive such as goblincities.tar.gz. You want to Say you have a theme archive such as ``goblincities.tar.gz`` and you
install this theme! Don't worry, it's fairly painless. want to install this theme! Don't worry, it's fairly painless.
Simply cd to the "install directory" for themes (by default, 1. ``cd ./user_dev/themes/``
``./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 2. Move the theme archive into this directory
Next, open up your mediagoblin configuration file (probably 3. ``tar -xzvf <tar-archive>``
4. Open your configuration file (probably named
``mediagoblin_local.ini``) and set the theme name:: ``mediagoblin_local.ini``) and set the theme name::
[mediagoblin] [mediagoblin]
# ... # ...
theme = goblincities theme = goblincities
Finally, "link the assets" so that they can be served by your web 5. 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 .. Note::
If you ever change the current theme in your config file, you
should re-run the above command! should re-run the above command!
(In the near future this should be even easier ;)) (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 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 ;) meanwhile ;)
@ -78,10 +81,11 @@ Configuring where things go
--------------------------- ---------------------------
By default, MediaGoblin's install directory for themes is By default, MediaGoblin's install directory for themes is
./user_dev/themes/ (relative to the MediaGoblin checkout or base ``./user_dev/themes/`` (relative to the MediaGoblin checkout or base
config file.) However, you can change this location easily. In your config file.) However, you can change this location easily with the
mediagoblin config file, under the section [mediagoblin] set the ``theme_install_dir`` setting in the ``[mediagoblin]`` section.
following parameter::
For example::
[mediagoblin] [mediagoblin]
# ... other parameters go here ... # ... other parameters go here ...
@ -98,8 +102,8 @@ Other variables you may consider setting:
`theme_linked_assets_dir` `theme_linked_assets_dir`
Your web server needs to serve the theme files out of some directory, Your web server needs to serve the theme files out of some directory,
and MediaGoblin will symlink the current theme's assets here. (See and MediaGoblin will symlink the current theme's assets here. See
"Linking assets" in the theme install section) the "Link the assets" setp in :ref:`theming-installing-section`.
Making a theme Making a theme
@ -109,9 +113,9 @@ 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 theme for an instance about hedgehogs! We'll call this the
"hedgehogified" theme. "hedgehogified" theme.
Change to where your theme_install_dir is set to (by default, Change to where your ``theme_install_dir`` is set to (by default,
``./user_dev/themes/`` ... make those directories if necessary and ``./user_dev/themes/`` ... make those directories or otherwise adjust
otherwise adjust if necessary):: if necessary)::
hedgehogified/ hedgehogified/
|- theme.cfg # configuration file for this theme |- theme.cfg # configuration file for this theme
@ -134,6 +138,8 @@ 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. This is the name that users will use to refer to activate
your theme. your theme.
.. Note::
It's important to note that templates based on MediaGoblin's code It's important to note that templates based on MediaGoblin's code
should be released as AGPLv3 (or later), like 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 itself. However, all the rest of your assets are up to you. In this
@ -177,7 +183,7 @@ this matter if you wish.
To fit with best licensing form, you should either preserve the To fit with best licensing form, you should either preserve the
MediaGoblin copyright header borrowing from a MediaGoblin template, or 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 # [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.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 can put whatever in here, but restating the license choice clearly is
probably a good idea. 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') }}"/> href="{{ request.staticdirect('/css/theme.css', 'theme') }}"/>
You can name the css file whatever you like. Now make the directory 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 You can now put custom CSS files in here and any CSS you add will
override default MediaGoblin CSS. 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:: 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. Where "yourtheme" is replaced with your theme name.