Merge branch 'master' of github.com:ametaireau/pelican

docs/conf.py

@@ -147,6 +147,10 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'raclette', u'Raclette Documentation',
+    ('index', 'raclette', u'Raclette Documentation',  # why "raclette" ?!
-     [u'Alexis Métaireau'], 1)
+     [u'Alexis Métaireau'], 1),
+    ('pelican-themes', 'pelican-themes', u'A theme manager for Pelican',
+     [u'Mickaël Raybaud'], 'en.1'),
+    ('fr/pelican-themes', 'pelican-themes', u'Un gestionnaire de thèmes pour Pelican',
+     [u'Mickaël Raybaud'], 'fr.1')
 ]

docs/fr/configuration.rst

@@ -123,7 +123,7 @@ THEME :
 TWITTER_USERNAME :
 	Permet d'afficher un bouton permettant le tweet des articles. 
 
-
+Pelican est fournit avec :doc:`pelican-themes`, un script permettant de gérer les thèmes
 
 
 

docs/fr/pelican-themes.rst

@@ -0,0 +1,172 @@
+pelican-themes
+##############
+
+
+
+Description
+===========
+
+``pelican-themes`` est un outil en lignes de commandes pour gérer les thèmes de Pelican.
+
+
+Utilisation:
+""""""""""""
+
+| pelican-themes [-h] [-l] [-i *chemin d'un thème* [*chemin d'un thème* ...]]
+|                      [-r *nom d'un thème* [*nom d'un thème* ...]]
+|                      [-s *chemin d'un thème* [*chemin d'un thème* ...]] [-v] [--version]
+
+Arguments:
+""""""""""
+
+
+-h, --help                      Afficher l'aide et quitter 
+
+-l, --list                      Montrer les thèmes installés
+
+-i chemin, --install chemin     Chemin(s) d'accès d'un ou plusieurs thème à installer
+
+-r nom, --remove nom            Noms d'un ou plusieurs thèmes à installer
+
+-s chemin, --symlink chemin     Fonctionne de la même façon que l'option ``--install``, mais crée un lien symbolique au lieu d'effectuer une copie du thème vers le répertoire des thèmes.
+                                Utile pour le développement de thèmes.
+
+-v, --verbose                   Sortie détaillée 
+
+--version                       Affiche la version du script et quitte
+
+
+
+Exemples
+========
+
+
+Lister les thèmes installés
+"""""""""""""""""""""""""""
+
+``pelican-themes`` peut afficher les thèmes disponibles.
+
+Pour cela, vous pouvez utiliser l'option ``-l`` ou ``--list``, comme ceci:
+
+.. code-block:: console
+
+    $ pelican-themes -l
+    notmyidea
+    two-column@
+    simple
+    $ pelican-themes --list
+    notmyidea
+    two-column@
+    simple
+
+Dans cet exemple, nous voyons qu'il y a trois thèmes d'installés: ``notmyidea``, ``simple`` and ``two-column``.
+
+``two-column`` est suivi d'un ``@`` par ce que c'est un lien symbolique (voir `Créer des liens symboliques`_).
+
+Notez que vous pouvez combiner l'option ``--list`` avec l'option ``--verbose``, pour afficher plus de détails:
+
+.. code-block:: console
+    
+    $ pelican-themes -v -l
+    /usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/notmyidea
+    /usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/two-column (symbolic link to `/home/skami/Dev/Python/pelican-themes/two-column')
+    /usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/simple
+
+
+Installer des thèmes
+""""""""""""""""""""
+
+Vous pouvez installer un ou plusieurs thèmes en utilisant l'option ``-i`` ou ``--install``.
+
+Cette option prends en argument le(s) chemin(s) d'accès du ou des thème(s) que vous voulez installer, et peut se combiner avec l'option ``--verbose``:
+
+.. code-block:: console
+
+    # pelican-themes --install ~/Dev/Python/pelican-themes/notmyidea-cms --verbose
+
+.. code-block:: console
+
+    # pelican-themes --install ~/Dev/Python/pelican-themes/notmyidea-cms\
+                               ~/Dev/Python/pelican-themes/martyalchin \
+                               --verbose
+
+.. code-block:: console
+
+    # pelican-themes -vi ~/Dev/Python/pelican-themes/two-column
+
+
+Supprimer des thèmes
+""""""""""""""""""""
+
+``pelican-themes`` peut aussi supprimer des thèmes précédemment installés grâce à l'option ``-r`` ou ``--remove``.
+
+Cette option prends en argument le ou les nom(s) des thèmes que vous voulez installer, et peux se combiner avec l'option ``--verbose``:
+
+.. code-block:: console
+
+    # pelican-themes --remove two-column
+
+.. code-block:: console
+
+    # pelican-themes -r martyachin notmyidea-cmd -v
+
+
+
+
+
+Créer des liens symboliques
+"""""""""""""""""""""""""""
+
+
+L'option ``-s`` ou ``--symlink`` de ``pelican-themes`` permet de lier symboliquement un thème.
+
+Cette option s'utilise exactement comme l'option ``--install``:
+
+.. code-block:: console
+    
+    # pelican-themes --symlink ~/Dev/Python/pelican-themes/two-column
+
+Dans l'exemple ci dessus, un lien symbolique pointant vers le thème ``two-column`` a été installé dans le répertoire des thèmes de Pelican, toute modification sur le thème ``two-column`` prendra donc effet immédiatement.
+
+Cela peut être pratique pour le développement de thèmes
+
+.. code-block:: console
+
+    $ sudo pelican-themes -s ~/Dev/Python/pelican-themes/two-column
+    $ pelican ~/Blog/content -o /tmp/out -t two-column
+    $ firefox /tmp/out/index.html
+    $ vim ~/Dev/Pelican/pelican-themes/two-coumn/static/css/main.css 
+    $ pelican ~/Blog/content -o /tmp/out -t two-column
+    $ cp /tmp/bg.png ~/Dev/Pelican/pelican-themes/two-coumn/static/img/bg.png
+    $ pelican ~/Blog/content -o /tmp/out -t two-column
+    $ vim ~/Dev/Pelican/pelican-themes/two-coumn/templates/index.html 
+    $ pelican ~/Blog/content -o /tmp/out -t two-column
+
+
+Notez que cette fonctionnalité nécessite d'avoir un système d'exploitation et un système de fichiers supportant les liens symboliques, elle n'est donc pas disponible sous Micro$oft®©™ Fenêtre®©™. 
+
+Faire plusieurs choses à la fois
+""""""""""""""""""""""""""""""""
+
+
+Les options ``--install``, ``--remove`` et ``--symlink`` peuvent être employées en même temps, ce qui permets de réaliser plusieurs opérations en même temps:
+
+.. code-block:: console
+
+    # pelican-themes --remove notmyidea-cms two-column \
+                     --install ~/Dev/Python/pelican-themes/notmyidea-cms-fr \
+                     --symlink ~/Dev/Python/pelican-themes/two-column \
+                     --verbose
+
+Dans cette exemple, le thème ``notmyidea-cms`` sera remplacé par le thème ``notmyidea-cms-fr`` et le thème ``two-column`` sera lié symboliquement...
+
+
+
+À voir également
+================
+
+-   http://docs.notmyidea.org/alexis/pelican/
+-   ``/usr/share/doc/pelican/`` si vous avez installé Pelican par le `dépôt APT <http://skami18.github.com/pelican-packages/>`_
+
+
+

docs/pelican-themes.rst

@@ -0,0 +1,166 @@
+pelican-themes
+##############
+
+
+
+Description
+===========
+
+``pelican-themes`` is a command line tool for managing themes for Pelican.
+
+
+Usage
+"""""
+
+| pelican-themes [-h] [-l] [-i theme path [theme path ...]]
+|                      [-r theme name [theme name ...]]
+|                      [-s theme path [theme path ...]] [-v] [--version]
+
+Optional arguments:
+"""""""""""""""""""
+
+
+-h, --help                              Show the help an exit
+
+-l, --list                              Show the themes already installed
+
+-i theme_path, --install theme_path     One or more themes to install
+
+-r theme_name, --remove theme_name      One or more themes to remove
+
+-s theme_path, --symlink theme_path     Same as "--install", but create a symbolic link instead of copying the theme.
+                                        Useful for theme development
+
+-v, --verbose                           Verbose output
+
+--version                               Print the version of this script
+
+
+
+Examples
+========
+
+
+Listing the installed themes
+""""""""""""""""""""""""""""
+
+With ``pelican-themes``, you can see the available themes by using the ``-l`` or ``--list`` option:
+
+.. code-block:: console
+
+    $ pelican-themes -l
+    notmyidea
+    two-column@
+    simple
+    $ pelican-themes --list
+    notmyidea
+    two-column@
+    simple
+
+In this example, we can see there is 3 themes available: ``notmyidea``, ``simple`` and ``two-column``.
+
+``two-column`` is prefixed with an ``@`` because this theme is not copied to the Pelican theme path, but just linked to it (see `Creating symbolic links`_ for details about creating symbolic links).
+
+Note that you can combine the ``--list`` option with the ``-v`` or ``--verbose`` option to get a more verbose output, like this:
+
+.. code-block:: console
+    
+    $ pelican-themes -v -l
+    /usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/notmyidea
+    /usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/two-column (symbolic link to `/home/skami/Dev/Python/pelican-themes/two-column')
+    /usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/simple
+
+
+Installing themes
+"""""""""""""""""
+
+You can install one or more themes using the ``-i`` or ``--install`` option.
+This option takes as argument the path(s) of the theme(s) you want to install, and can be combined with the verbose option:
+
+.. code-block:: console
+
+    # pelican-themes --install ~/Dev/Python/pelican-themes/notmyidea-cms --verbose
+
+.. code-block:: console
+
+    # pelican-themes --install ~/Dev/Python/pelican-themes/notmyidea-cms\
+                               ~/Dev/Python/pelican-themes/martyalchin \
+                               --verbose
+
+.. code-block:: console
+
+    # pelican-themes -vi ~/Dev/Python/pelican-themes/two-column
+
+
+Removing themes
+"""""""""""""""
+
+Pelican themes can also removes themes from the Pelican themes path.
+The ``-r`` or ``--remove`` takes as argument the name(s) of the theme(s) you want to remove, and can be combined with the ``--verbose`` option.
+
+.. code-block:: console
+
+    # pelican-themes --remove two-column
+
+.. code-block:: console
+
+    # pelican-themes -r martyachin notmyidea-cmd -v
+
+
+
+
+
+Creating symbolic links
+"""""""""""""""""""""""
+
+``pelican-themes`` can also install themes by creating symbolic links instead of copying the whole themes in the Pelican themes path.
+
+To symbolically link a theme, you can use the ``-s`` or ``--symlink``, which works exactly as the ``--install`` option:
+
+.. code-block:: console
+    
+    # pelican-themes --symlink ~/Dev/Python/pelican-themes/two-column
+
+In this example, the ``two-column`` theme is now symbolically linked to the Pelican themes path, so we can use it, but we can also modify it without having to reinstall it after each modification.
+
+This is useful for theme development:
+
+.. code-block:: console
+
+    $ sudo pelican-themes -s ~/Dev/Python/pelican-themes/two-column
+    $ pelican ~/Blog/content -o /tmp/out -t two-column
+    $ firefox /tmp/out/index.html
+    $ vim ~/Dev/Pelican/pelican-themes/two-coumn/static/css/main.css 
+    $ pelican ~/Blog/content -o /tmp/out -t two-column
+    $ cp /tmp/bg.png ~/Dev/Pelican/pelican-themes/two-coumn/static/img/bg.png
+    $ pelican ~/Blog/content -o /tmp/out -t two-column
+    $ vim ~/Dev/Pelican/pelican-themes/two-coumn/templates/index.html 
+    $ pelican ~/Blog/content -o /tmp/out -t two-column
+
+
+
+Doing several things at once
+""""""""""""""""""""""""""""
+
+The ``--install``, ``--remove`` and ``--symlink`` option are not mutually exclusive, so you can combine them in the same command line to do more than one operation at time, like this:
+
+
+.. code-block:: console
+
+    # pelican-themes --remove notmyidea-cms two-column \
+                     --install ~/Dev/Python/pelican-themes/notmyidea-cms-fr \
+                     --symlink ~/Dev/Python/pelican-themes/two-column \
+                     --verbose
+
+In this example,  the theme ``notmyidea-cms`` is replaced by the theme ``notmyidea-cms-fr`` 
+
+
+
+
+See also
+========
+
+-   http://docs.notmyidea.org/alexis/pelican/
+-   ``/usr/share/doc/pelican/`` if you have installed Pelican using the `APT repository <http://skami18.github.com/pelican-packages/>`_
+
+

docs/settings.rst

@@ -195,6 +195,8 @@ Here is `a guide on how to create your theme
 
 You can find a list of themes at http://github.com/ametaireau/pelican-themes.
 
+Pelican comes with :doc:`pelican-themes` a small script for managing themes.
+
 The `notmyidea` theme can make good use of the following settings. I recommend
 to use them too in your themes.
 
@@ -278,3 +280,4 @@ Setting name (default value)                        what does it do?
 `SKRIBIT_WIDGET_ID`                                 Widget identifier (See Skribit part below).
 ================================================    =====================================================
 
+.. _pelican-themes: :doc:`pelican-themes`

tools/pelican-themes

@@ -4,53 +4,70 @@
 import os, sys, shutil
 import argparse
 
-
-def err(msg, die=None):
-    sys.stderr.write(str(msg) + '\n')
-    if die:
-        sys.exit((die if type(die) is int else 1))
-
 try:
     import pelican
-
-    global themes_path
-    themes_path = os.path.join(
-        os.path.dirname(
-            os.path.abspath(
-                pelican.__file__
-            )
-        ),
-        'themes'
-    )
 except:
     err('Cannot import pelican.\nYou must install Pelican in order to run this script.', -1)
 
 
-__version__ = '0.1'
+global _THEMES_PATH
+_THEMES_PATH = os.path.join(
+    os.path.dirname(
+        os.path.abspath(
+            pelican.__file__
+    )
+    ),
+    'themes'
+)
+
+__version__ = '0.2'
 _BUILTIN_THEMES = ['simple', 'notmyidea']
 
 
+def err(msg, die=None):
+    """Print an error message and exits if an exit code is given"""
+    sys.stderr.write(str(msg) + '\n')
+    if die:
+        sys.exit((die if type(die) is int else 1))
+
+
 def main():
+    """Main function"""
+
     parser = argparse.ArgumentParser(description="""Install themes for Pelican""")
 
-    parser.add_argument('-l', '--list', dest='list', action="store_true",
+    excl= parser.add_mutually_exclusive_group()
-                        help="Show the themes already installed")
+    excl.add_argument('-l', '--list', dest='action', action="store_const", const='list',
+                        help="Show the themes already installed and exit")
+    excl.add_argument('-p', '--path', dest='action', action="store_const", const='path',
+                        help="Show the themes path and exit")
+    excl.add_argument('-V', '--version', action='version', version='pelican-themes v{0}'.format(__version__),
+            help='Print the version of this script')
+
+
     parser.add_argument('-i', '--install', dest='to_install', nargs='+', metavar="theme path",
         help='The themes to install ')
     parser.add_argument('-r', '--remove', dest='to_remove', nargs='+', metavar="theme name",
         help='The themes to remove')
     parser.add_argument('-s', '--symlink', dest='to_symlink', nargs='+', metavar="theme path",
         help="Same as `--install', but create a symbolic link instead of copying the theme. Useful for theme development")
+    parser.add_argument('-c', '--clean', dest='clean', action="store_true",
+                        help="Remove the broken symbolic links of the theme path")
+
+
     parser.add_argument('-v', '--verbose', dest='verbose', action="store_true",
                         help="Verbose output")
-    parser.add_argument('--version', action='version', version=__version__,
+
-            help='Print the version of this script')
+
     args = parser.parse_args()
 
-
+    
-    if args.list:
+    if args.action:
-        list_themes(args.verbose)
+        if args.action is 'list':
-    else:
+            list_themes(args.verbose)
+        elif args.action is 'path':
+            print(_THEMES_PATH)
+    elif args.to_install or args.to_remove or args.to_symlink or args.clean:
 
         if args.to_remove:
             if args.verbose:
@@ -73,20 +90,29 @@ def main():
             for i in args.to_symlink:
                 symlink(i, v=args.verbose)
 
+        if args.clean:
+            if args.verbose:
+                print('Cleaning the themes directory...')
+            
+            clean(v=args.verbose)
+    else:
+        print('No argument given... exiting.')
 
 
 def themes():
-    for i in os.listdir(themes_path):
+    """Returns the list of the themes"""
-        e = os.path.join(themes_path, i)
+    for i in os.listdir(_THEMES_PATH):
+        e = os.path.join(_THEMES_PATH, i)
 
         if os.path.isdir(e):
             if os.path.islink(e):
-                yield (e, os.path.realpath(e))
+                yield (e, os.readlink(e))
             else:
                 yield (e, None)
 
 
 def list_themes(v=False):
+    """Display the list of the themes"""
     for t, l in themes():
         if not v:
             t = os.path.basename(t)
@@ -100,14 +126,13 @@ def list_themes(v=False):
 
 
 def remove(theme_name, v=False):
+    """Removes a theme"""
 
     theme_name = theme_name.replace('/','')
-    target = os.path.join(themes_path, theme_name)
+    target = os.path.join(_THEMES_PATH, theme_name)
 
     if theme_name in _BUILTIN_THEMES:
         err(theme_name + ' is a builtin theme.\nYou cannot remove a builtin theme with this script, remove it by hand if you want.')
-    elif not os.path.exists(target):
-        err(target + ' : no such file or directory')
     elif os.path.islink(target):
         if v:
             print('Removing link `' + target + "'")
@@ -116,18 +141,21 @@ def remove(theme_name, v=False):
         if v:
             print('Removing directory `' + target + "'")
         shutil.rmtree(target)
-    else:
+    elif os.path.exists(target):
         err(target + ' : not a valid theme') 
+    else:
+        err(target + ' : no such file or directory')
 
 
 def install(path, v=False):
+    """Installs a theme"""
     if not os.path.exists(path):
         err(path + ' : no such file or directory')
     elif not os.path.isdir(path):
         err(path + ' : no a directory')
     else:
         theme_name = os.path.basename(os.path.normpath(path))
-        theme_path = os.path.join(themes_path, theme_name)
+        theme_path = os.path.join(_THEMES_PATH, theme_name)
         if os.path.exists(theme_path):
             err(path + ' : already exists')
         else:
@@ -138,14 +166,16 @@ def install(path, v=False):
             except Exception, e:
                 err("Cannot copy `{p}' to `{t}':\n{e}".format(p=path, t=theme_path, e=str(e)))
 
+
 def symlink(path, v=False):
+    """Symbolically link a theme"""
     if not os.path.exists(path):
         err(path + ' : no such file or directory')
     elif not os.path.isdir(path):
         err(path + ' : no a directory')
     else:
         theme_name = os.path.basename(os.path.normpath(path))
-        theme_path = os.path.join(themes_path, theme_name)
+        theme_path = os.path.join(_THEMES_PATH, theme_name)
         if os.path.exists(theme_path):
             err(path + ' : already exists')
         else:
@@ -157,6 +187,29 @@ def symlink(path, v=False):
                 err("Cannot link `{p}' to `{t}':\n{e}".format(p=path, t=theme_path, e=str(e)))
 
 
+def is_broken_link(path):
+    """Returns True if the path given as is a broken symlink"""
+    path = os.readlink(path)
+    return not os.path.exists(path)
+
+
+def clean(v=False):
+    """Removes the broken symbolic links"""
+    c=0
+    for path in os.listdir(_THEMES_PATH):
+        path = os.path.join(_THEMES_PATH, path)
+        if os.path.islink(path):
+            if is_broken_link(path):
+                if v:
+                    print('Removing {0}'.format(path))
+                try:
+                    os.remove(path)
+                except OSError, e:
+                    print('Error: cannot remove {0}'.format(path))
+                else:
+                    c+=1
+
+    print("\nRemoved {0} broken links".format(c))
     
 if __name__ == '__main__':
     main()