From 079e9f878e8b0b14da02cc3495cf89e7fde55c23 Mon Sep 17 00:00:00 2001 From: Guillaume Date: Wed, 26 Jan 2011 17:36:59 +0100 Subject: [PATCH] Francisation des noms de fichier de la doc fr --- docs/fr/{basis.rst => bases.rst} | 0 docs/fr/configuration.rst | 154 ++++++++++++++++++++++ docs/fr/conventions.rst | 18 +++ docs/fr/index.rst | 14 +- docs/fr/index.rst.save | 53 -------- docs/fr/{install.rst => installation.rst} | 0 docs/fr/internals.rst | 81 ------------ docs/fr/settings.rst | 111 ---------------- docs/fr/themes.rst | 106 --------------- 9 files changed, 178 insertions(+), 359 deletions(-) rename docs/fr/{basis.rst => bases.rst} (100%) create mode 100644 docs/fr/configuration.rst create mode 100644 docs/fr/conventions.rst delete mode 100644 docs/fr/index.rst.save rename docs/fr/{install.rst => installation.rst} (100%) delete mode 100644 docs/fr/internals.rst delete mode 100644 docs/fr/settings.rst delete mode 100644 docs/fr/themes.rst diff --git a/docs/fr/basis.rst b/docs/fr/bases.rst similarity index 100% rename from docs/fr/basis.rst rename to docs/fr/bases.rst diff --git a/docs/fr/configuration.rst b/docs/fr/configuration.rst new file mode 100644 index 00000000..5f61a3ba --- /dev/null +++ b/docs/fr/configuration.rst @@ -0,0 +1,154 @@ +Fichier de configuration +************************ + +On va créer un fichier de configuration que l’on va appeler **settings.py**. On peut +utiliser Pelican sans faire ce fichier, mais il faudrait à chaque fois passer les paramètres +en ligne de commande. Et comme il va nous servir à faire d’autres choses bien utile, +autant l’appréhender de suite. Cependant, nous n’allons voir que la base pour l’instant. + +Paramètres de base +================== + +AUTHOR : + Désigne l’auteur par défaut ; + +DEFAULT_CATEGORY : + La catégorie par défaut des articles. Si ce paramètre n’est + pas documenté, il prendra la valeur misc — pour miscellaneous (divers en français) ; + +SITENAME : + Le nom de votre site ; + +OUTPUT_PATH : + Le répertoire de sortie du blog. + +Quand je dis qu’on va faire simple, on fait simple ! +Passons donc à ce quoi doit ressembler le fichier de configuration :: + + # -*- coding: utf-8 -*- + AUTHOR = "Guillaume" + DEFAULT_CATEGORY = "GNU-Linux" + SITENAME = "Free Culture" + + +Si vous avez un serveur comme Apache de configuré pour votre machine, vous +pouvez paramétrer le répertoire de sortie vers **/var/www/blog** par exemple :: + + OUTPUT_PATH = "/var/www/blog" + +Une remarque importante. Si vous avez besoin de passer un caractère accentué, il +faut le préciser que la chaine est en unicode en faisant par exemple +*AUTHOR = u"Guillaume LAMÉ"* + +Pour bien vérifier que les paramètres sont bien pris en compte, nous allons enlever les lignes *:author: Guillaume* et *:category: GNU-Linux* de notre fichier +**premier_article.rst** et regénérer le blog. + +Rafraichissez votre page, ce devrait être bon. + +Nous allons maintenant passer en revue les différents paramètres de Pelican. Je les +ai regroupé par thème. Cependant, c’est surtout un listing avant de rentrer dans les +détails au prochain chapitre. + +Flux de syndication +=================== + +CATEGORY_FEED : + Chemin d’écriture des flux Atom liés aux catégories ; + +CATEGORY_FEED_RSS : + Idem pour les flux rss (Optionnel); + +FEED : + Chemin du flux Atom global ; + +FEED_RSS : + Chemin du flux Rss global (Optionnel); + +TAG_FEED : + Chemin des flux Atom pour les tags (Optionnel); + +TAG_FEED_RSS : + Chemin des flux Rss pour les tags (Optionnel). + + +Traductions +=========== + +DEFAULT_LANG : + Le langage par défaut à utiliser. «*en*» par défaut ; + +TRANSLATION_FEED : + Chemin du flux pour les traductions. + + +Thèmes +====== + +CSS_FILE : + Fichier css à utiliser si celui-ci est différent du fichier par défaut (*main.css*) ; + +DISPLAY_PAGES_ON_MENU : + Affiche ou non les pages statiques sur le menu du thème ; + +DISQUS_SITENAME : + Indiquer le nom du site spécifié sur Disqus ; + +GITHUB_URL : + Indiquez votre url Github ; + +GOOGLE_ANALYTICS : + 'UA-XXXX-YYYY' pour activer Google analytics ; + +JINJA_EXTENSIONS : + Liste d'extension Jinja2 que vous souhaitez utiliser ; + +LINKS : + Une liste de tuples (Titre, url) pour afficher la liste de lien ; + +PDF_PROCESSOR : + Génère ou non les articles et pages au format pdf ; + +REVERSE_ARCHIVE_ORDER : + Met les articles plus récent en tête de l'archive ; + +SOCIAL : + Une liste de tuples (Titre, url) pour afficher la liste de lien dans la section "Social" ; + +STATIC_THEME_PATHS : + Répertoire du thème que vous souhaitez importer dans l'arborescence finale ; + +THEME : + Thème à utiliser: + +TWITTER_USERNAME : + Permet d'afficher un bouton permettant le tweet des articles. + + + + + +Paramètres divers +================= + +FALLBACK_ON_FS_DATE : + Si *True*, Pelican se basera sur le *mtime* du fichier s'il n'y a pas de date spécifiée dans le fichier de l'article ; + +KEEP_OUTPUT DIRECTORY : + Ne génère que les fichiers modifiés et n'efface pas le repertoire de sortie ; + +MARKUP : + Langage de balisage à utiliser ; + +PATH : + Répertoire à suivre pour les fichiers inclus ; + +SITEURL : + URL de base de votre site ; + +STATIC_PATHS : + Les chemins statiques que vous voulez avoir accès sur le chemin de sortie "statique" ; + + + + + diff --git a/docs/fr/conventions.rst b/docs/fr/conventions.rst new file mode 100644 index 00000000..bf88c07e --- /dev/null +++ b/docs/fr/conventions.rst @@ -0,0 +1,18 @@ +Conventions +########### + +Environnement de test +===================== + +Les exemples sont basées sur une distribution Debian. Pour les autres distributions, +il y aura des ajustements à faire, notamment pour l’installation de Pelican. Les +noms des paquets peuvent changer. + +Conventions typographiques +========================== + +Un petit rappel concernant les codes sources. + + * $ correspond à une ligne à exécuter en tant qu’utilisateur courant du systême ; + * # correspond à une ligne à exécuter en tant que root ; + * **settings.py** : Les noms des répertoires et fichiers sont en gras. diff --git a/docs/fr/index.rst b/docs/fr/index.rst index 3d77a923..cdb0868f 100644 --- a/docs/fr/index.rst +++ b/docs/fr/index.rst @@ -29,8 +29,8 @@ Vous n'avez pas remarqué ? "Pelican" est un anagramme pour "Calepin" ;) Code source =========== -Vous pouvez accéder au code source via mercurial sur http://hg.notmyidea.org/pelican/ -ou via git à l'adresse http://github.com/ametaireau/pelican/ +Vous pouvez accéder au code source via git à l'adresse +http://github.com/ametaireau/pelican/ Feedback ! ========== @@ -46,9 +46,7 @@ Documentation .. toctree:: :maxdepth: 2 - install - basis - settings - themes - internals - faq + conventions + installation + bases + configuration diff --git a/docs/fr/index.rst.save b/docs/fr/index.rst.save deleted file mode 100644 index 822f0fcd..00000000 --- a/docs/fr/index.rst.save +++ /dev/null @@ -1,53 +0,0 @@ -Pelican -####### - -Pelican est un generateur de blog simple codé en python - -* Écrivez vos articles directement dans votre éditeur favori (vim !) et - directement en syntaxe reStructuredText ou Markdown ; -* Un outil simple en ligne de conmmande pour (re)générer le blog ; -* Sortie complètement statique, facile pour l'héberger n'importe où ; - -Fonctionnalités -=============== - -Pelican supporte actuellement : - -* des articles de blog ; -* des pages statiques ; -* les commentaires via un service externe (`disqus `_) - Notez qu'étant bien un service externe assez pratique, vous ne gérez pas - vous même les commentaires. Ce qui pourrait occasionner une perte de vos données; -* support de template (les templates sont crées avec Jinja 2 `jinja2 `_) ; -* génération optionnelle de vos pages et articles en pdf. - -Pourquoi le nom "Pelican" ? -============================ - -Vous n'avez pas remarqué ? "Pelican" est un anagramme pour "Calepin" ;) - -Code source -=========== - -Vous pouvez accéder au code source via mercurial sur http://hg.notmyidea.org/pelican/ -ou via git à l'adresse http://github.com/ametaireau/pelican/ - -Feedback ! -========== - -Si vous voulez de nouvelles fonctionnalitées pour Pelican, n'hésitez pas à me le dire, -à cloner le dépôt, etc … C'est open source !!! - -Contactez Ale "alexis at notmyidea dot org" pour quelques requêtes ou retour d'expérience que ce soi ! - -Documentation -============= - -.. toctree:: - :maxdepth: 2 - - getting_started - settings - themes - internals - faq diff --git a/docs/fr/install.rst b/docs/fr/installation.rst similarity index 100% rename from docs/fr/install.rst rename to docs/fr/installation.rst diff --git a/docs/fr/internals.rst b/docs/fr/internals.rst deleted file mode 100644 index 80fc8661..00000000 --- a/docs/fr/internals.rst +++ /dev/null @@ -1,81 +0,0 @@ -Pelican internals -################# - -This section describe how pelican is working internally. As you'll see, it's -quite simple, but a bit of documentation doesn't hurt :) - -Overall structure -================= - -What `pelican` does, is taking a list of files, and processing them, to some -sort of output. Usually, the files are restructured text and markdown files, -and the output is a blog, but it can be anything you want. - -I've separated the logic in different classes and concepts: - -* `writers` are responsible of all the writing process of the - files. It's writing .html files, RSS feeds and so on. Since those operations - are commonly used, the object is created once, and then passed to the - generators. - -* `readers` are used to read from various formats (Markdown, and Restructured - Text for now, but the system is extensible). Given a file, they return - metadata (author, tags, category etc) and content (HTML formated) - -* `generators` generate the different outputs. For instance, pelican comes with - `ArticlesGenerator` and `PageGenerator`, into others. Given - a configurations, they can do whatever they want. Most of the time it's - generating files from inputs. - -* `pelican` also uses `templates`, so it's easy to write you own theme. The - syntax is `jinja2`, and, trust me, really easy to learn, so don't hesitate - a second. - -How to implement a new reader ? -=============================== - -There is an awesome markup language you want to add to pelican ? -Well, the only thing you have to do is to create a class that have a `read` -method, that is returning an HTML content and some metadata. - -Take a look to the Markdown reader:: - - class MarkdownReader(object): - - def read(self, filename): - """Parse content and metadata of markdown files""" - text = open(filename) - md = Markdown(extensions = ['meta', 'codehilite']) - content = md.convert(text) - - metadatas = {} - for name, value in md.Meta.items(): - if name in _METADATAS_FIELDS: - meta = _METADATAS_FIELDS[name](value[0]) - else: - meta = value[0] - metadatas[name.lower()] = meta - return content, metadatas - -Simple isn't it ? - -How to implement a new generator ? -================================== - -Generators have basically two important methods. You're not forced to create -both, only the existing ones will be called. - -* `generate_context`, that is called in a first place, for all the generators. - Do whatever you have to do, and update the global context if needed. This - context is shared between all generators, and will be passed to the - templates. For instance, the `PageGenerator` `generate_context` method find - all the pages, transform them into objects, and populate the context with - them. Be careful to *not* output anything using this context at this stage, - as it is likely to change by the effect of others generators. - -* `generate_output` is then called. And guess what is it made for ? Oh, - generating the output :) That's here that you may want to look at the context - and call the methods of the `writer` object, that is passed at the first - argument of this function. In the `PageGenerator` example, this method will - look at all the pages recorded in the global context, and output a file on - the disk (using the writer method `write_file`) for each page encountered. diff --git a/docs/fr/settings.rst b/docs/fr/settings.rst deleted file mode 100644 index e59d1b5b..00000000 --- a/docs/fr/settings.rst +++ /dev/null @@ -1,111 +0,0 @@ -Settings -######## - -Specifying the settings -======================= - -Pelican is configurable thanks to a configuration file, that you can pass to -the command line:: - - $ pelican -s path/to/your/settingsfile.py path - -Settings are given as the form of a python module (a file). You can have an -example by looking at `/samples/pelican.conf.py -`_ - -All the settings identifiers must be set in caps, otherwise they will not be -processed. - -Here are the available settings. Please note that all the settings you put in -this file will be passed to the templates as well. - -======================= ======================================================= -Setting name what it does ? -======================= ======================================================= -`AUTHOR` Default author (put your name) -`CATEGORY_FEED` Where to put the atom categories feeds. default is - `feeds/%s.atom.xml`, where %s is the name of the - category. -`CATEGORY_FEED_RSS` Where to put the categories rss feeds. default is None - (no rss) -`CSS_FILE` To specify the CSS file you want to load, if it's not - the default one ('main.css') -`DEFAULT_CATEGORY` The default category to fallback on. `misc` by default. -`DEFAULT_LANG` The default language to use. Default is 'en'. -`DISPLAY_PAGES_ON_MENU` Display or not the pages on the menu of the template. - Templates can follow or not this settings. -`FALLBACK_ON_FS_DATE` If True, pelican will use the file system dates infos - (mtime) if it can't get informations from the - metadata? -`FEED` relative url to output the atom feed. Default is - `feeds/all.atom.xml` -`FEED_RSS` relative url to output the rss feed. Default is - None (no rss) -`JINJA_EXTENSIONS` A list of any Jinja2 extensions you want to use. - Default is no extensions (the empty list). -`KEEP_OUTPUT_DIRECTORY` Keep the output directory and just update all the generated files. - Default is to delete the output directory. -`MARKUP` A list of available markup languages you want to use. - For the moment, only available values are `rst` and `md`. -`OUTPUT_PATH` Where to output the generated files. Default to - "output" -`PATH` path to look at for input files. -`PDF_PROCESSOR` Put True if you want to have PDF versions of your - documents. You will need to install `rst2pdf`. -`REVERSE_ARCHIVE_ORDER` Reverse the archives order. (True makes it in - descending order: the newer first) -`SITEURL` base URL of your website. -`SITENAME` Your site name, -`STATIC_PATHS` The static paths you want to have accessible on the - output path "static". By default, pelican will copy - the 'images' folder to the output folder. -`STATIC_THEME_PATHS` Static theme paths you want to copy. Default values - is `static`, but if your theme have others static paths, - you can put them here. -`THEME` theme to use to product the output. can be the - complete static path to a theme folder, or chosen - between the list of default themes (see below) -`TRANSLATION_FEED` Where to put the RSS feed for translations. Default - is feeds/all-%s.atom.xml where %s is the name of the - lang. -======================= ======================================================= - -Themes -====== - -3 themes are available. You can specify them using the `-t` option: - -* notmyidea -* simple (a synonym for "full text" :) -* martyalchin - -You can define your own theme too, and specify it's emplacement in the same -way (be sure to specify the full absolute path to it). - -Here is `a guide on how to create your theme -`_ - -The `notmyidea` theme can make good use of the following settings. I recommend -to use them too in your themes. - -======================= ======================================================= -Setting name what it does ? -======================= ======================================================= -`DISQUS_SITENAME` Pelican can handle disqus comments, specify the - sitename you've filled in on disqus -`GITHUB_URL` Your github URL (if you have one), it will then - use it to create a github ribbon. -`GOOGLE_ANALYTICS` 'UA-XXXX-YYYY' to activate google analytics. -`LINKS` A list of tuples (Title, Url) for links to appear on - the header. -`SOCIAL` A list of tuples (Title, Url) to appear in the "social" - section. -`TWITTER_USERNAME` Allows to add a button on the articles to tweet about - them. Add you twitter username if you want this - button to appear. -======================= ======================================================= - -In addition, you can use the "wide" version of the `notmyidea` theme, by -adding that in your configuration:: - - CSS_FILE = "wide.css" diff --git a/docs/fr/themes.rst b/docs/fr/themes.rst deleted file mode 100644 index a9c2262b..00000000 --- a/docs/fr/themes.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. _theming-pelican-fr: - -How to create themes for pelican -################################ - -Pelican uses the great `jinja2 `_ templating engine to -generate it's HTML output. The jinja2 syntax is really simple. If you want to -create your own theme, feel free to take inspiration from the "simple" theme, -which is available `here -`_ - -Structure -========= - -To make your own theme, you must follow the following structure:: - - ├── static - │   ├── css - │   └── images - └── templates - ├── archives.html // to display archives - ├── article.html // processed for each article - ├── categories.html // must list all the categories - ├── category.html // processed for each category - ├── index.html // the index. List all the articles - ├── page.html // processed for each page - ├── tag.html // processed for each tag - └── tags.html // must list all the tags. Can be a tag cloud. - -* `static` contains all the static content. It will be copied on the output - `theme/static` folder then. I've put the css and image folders, but they are - just examples. Put what you need here. - -* `templates` contains all the templates that will be used to generate the content. - I've just put the mandatory templates here, you can define your own if it helps - you to organize yourself while doing the theme. - -Templates and variables -======================= - -It's using a simple syntax, that you can embbed into your html pages. -This document describes which templates should exists on a theme, and which -variables will be passed to each template, while generating it. - -All templates will receive the variables defined in your settings file, if they -are in caps. You can access them directly. - -Common variables ----------------- - -All of those settings will be given to all templates. - -============= =================================================== -Variable Description -============= =================================================== -articles That's the list of articles, ordsered desc. by date - all the elements are `Article` objects, so you can - access their properties (e.g. title, summary, author - etc. -dates The same list of article, but ordered by date, - ascending -tags A dict containing each tags (keys), and the list of - relative articles. -categories A dict containing each category (keys), and the - list of relative articles. -pages The list of pages -============= =================================================== - -category.html -------------- - -This template will be processed for each of the existing categories, and will -finally remain at output/category/`category_name`.html. - -============= =================================================== -Variable Description -============= =================================================== -articles The articles of this category -category The name of the category being processed -============= =================================================== - -article.html -------------- - -This template will be processed for each article. .html files will be outputed -in output/`article_name`.html. Here are the specific variables it gets. - -============= =================================================== -Variable Description -============= =================================================== -article The article object to be displayed -category The name of the category of the current article -============= =================================================== - -tag.html --------- - -For each tag, this template will be processed. It will create .html files in -/output/tag/`tag_name`.html - -============= =================================================== -Variable Description -============= =================================================== -tag The name of the tag being processed -articles Articles related to this tag -============= ===================================================