diff --git a/docs/conf.py b/docs/conf.py index 76167eaf..dea52e2d 100644 --- a/docs/conf.py +++ b/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', - [u'Alexis Métaireau'], 1) + ('index', 'raclette', u'Raclette Documentation', # why "raclette" ?! + [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') ] diff --git a/docs/fr/configuration.rst b/docs/fr/configuration.rst index 5f61a3ba..695a0b0e 100644 --- a/docs/fr/configuration.rst +++ b/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 diff --git a/docs/fr/pelican-themes.rst b/docs/fr/pelican-themes.rst new file mode 100644 index 00000000..810fa785 --- /dev/null +++ b/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 `_ + + + diff --git a/docs/pelican-themes.rst b/docs/pelican-themes.rst new file mode 100644 index 00000000..bd2dba77 --- /dev/null +++ b/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 `_ + + diff --git a/docs/settings.rst b/docs/settings.rst index ddc41681..355716e9 100644 --- a/docs/settings.rst +++ b/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`