pelican/docs/fr/_build/latex/Raclette.tex

% Generated by Sphinx.
\documentclass[letterpaper,10pt,english]{manual}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{longtable}
\usepackage{sphinx}


\title{Raclette Documentation}
\date{January 24, 2011}
\release{2}
\author{Alexis Métaireau}
\newcommand{\sphinxlogo}{}
\renewcommand{\releasename}{Release}
\makeindex
\makemodindex

\makeatletter
\def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax%
    \let\PYG@ul=\relax \let\PYG@tc=\relax%
    \let\PYG@bc=\relax \let\PYG@ff=\relax}
\def\PYG@tok#1{\csname PYG@tok@#1\endcsname}
\def\PYG@toks#1+{\ifx\relax#1\empty\else%
    \PYG@tok{#1}\expandafter\PYG@toks\fi}
\def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{%
    \PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}}
\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}}

\def\PYG@tok@gd{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.00,0.00}{##1}}}
\def\PYG@tok@gu{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}}
\def\PYG@tok@gt{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.25,0.82}{##1}}}
\def\PYG@tok@gs{\let\PYG@bf=\textbf}
\def\PYG@tok@gr{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}}
\def\PYG@tok@cm{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\def\PYG@tok@vg{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\def\PYG@tok@m{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\def\PYG@tok@mh{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\def\PYG@tok@cs{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}\def\PYG@bc##1{\colorbox[rgb]{1.00,0.94,0.94}{##1}}}
\def\PYG@tok@ge{\let\PYG@it=\textit}
\def\PYG@tok@vc{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\def\PYG@tok@il{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\def\PYG@tok@go{\def\PYG@tc##1{\textcolor[rgb]{0.19,0.19,0.19}{##1}}}
\def\PYG@tok@cp{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\def\PYG@tok@gi{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.63,0.00}{##1}}}
\def\PYG@tok@gh{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}}
\def\PYG@tok@ni{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.84,0.33,0.22}{##1}}}
\def\PYG@tok@nl{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.13,0.44}{##1}}}
\def\PYG@tok@nn{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\def\PYG@tok@no{\def\PYG@tc##1{\textcolor[rgb]{0.38,0.68,0.84}{##1}}}
\def\PYG@tok@na{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\def\PYG@tok@nb{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\def\PYG@tok@nc{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\def\PYG@tok@nd{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.33,0.33,0.33}{##1}}}
\def\PYG@tok@ne{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\def\PYG@tok@nf{\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.49}{##1}}}
\def\PYG@tok@si{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.44,0.63,0.82}{##1}}}
\def\PYG@tok@s2{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\def\PYG@tok@vi{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\def\PYG@tok@nt{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.45}{##1}}}
\def\PYG@tok@nv{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\def\PYG@tok@s1{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\def\PYG@tok@gp{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\def\PYG@tok@sh{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\def\PYG@tok@ow{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\def\PYG@tok@sx{\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\def\PYG@tok@bp{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\def\PYG@tok@c1{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\def\PYG@tok@kc{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\def\PYG@tok@c{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\def\PYG@tok@mf{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\def\PYG@tok@err{\def\PYG@bc##1{\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{##1}}}
\def\PYG@tok@kd{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\def\PYG@tok@ss{\def\PYG@tc##1{\textcolor[rgb]{0.32,0.47,0.09}{##1}}}
\def\PYG@tok@sr{\def\PYG@tc##1{\textcolor[rgb]{0.14,0.33,0.53}{##1}}}
\def\PYG@tok@mo{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\def\PYG@tok@mi{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\def\PYG@tok@kn{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\def\PYG@tok@o{\def\PYG@tc##1{\textcolor[rgb]{0.40,0.40,0.40}{##1}}}
\def\PYG@tok@kr{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\def\PYG@tok@s{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\def\PYG@tok@kp{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\def\PYG@tok@w{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}}
\def\PYG@tok@kt{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.13,0.00}{##1}}}
\def\PYG@tok@sc{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\def\PYG@tok@sb{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\def\PYG@tok@k{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\def\PYG@tok@se{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\def\PYG@tok@sd{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}

\def\PYGZbs{\char`\\}
\def\PYGZus{\char`\_}
\def\PYGZob{\char`\{}
\def\PYGZcb{\char`\}}
\def\PYGZca{\char`\^}
\def\PYGZsh{\char`\#}
\def\PYGZpc{\char`\%}
\def\PYGZdl{\char`\$}
\def\PYGZti{\char`\~}
% for compatibility with earlier versions
\def\PYGZat{@}
\def\PYGZlb{[}
\def\PYGZrb{]}
\makeatother

\begin{document}

\maketitle
\tableofcontents
\hypertarget{--doc-index}{}


Pelican est un generateur de blog simple codé en python
\begin{itemize}
\item {} 
Écrivez vos articles directement dans votre éditeur favori (vim !) et
directement en syntaxe reStructuredText ou Markdown ;

\item {} 
Un outil simple en ligne de conmmande pour (re)générer le blog ;

\item {} 
Sortie complètement statique, facile pour l'héberger n'importe où ;

\end{itemize}


\chapter{Fonctionnalités}

Pelican supporte actuellement :
\begin{itemize}
\item {} 
des articles de blog ;

\item {} 
des pages statiques ;

\item {} 
les commentaires via un service externe (\href{http://disqus.com}{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;

\item {} 
support de template (les templates sont crées avec Jinja 2 \href{http://jinjna.pocoo.org}{jinja2}) ;

\item {} 
génération optionnelle de vos pages et articles en pdf.

\end{itemize}


\chapter{Pourquoi le nom ``Pelican'' ?}

Vous n'avez pas remarqué ? ''Pelican'' est un anagramme pour ``Calepin'' ;)


\chapter{Code source}

Vous pouvez accéder au code source via mercurial sur  \href{http://hg.notmyidea.org/pelican/}{http://hg.notmyidea.org/pelican/}
ou via git à l'adresse \href{http://github.com/ametaireau/pelican/}{http://github.com/ametaireau/pelican/}


\chapter{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 moi à ``alexis at notmyidea dot org'' pour quelques requêtes ou retour d'expérience que ce soi !


\chapter{Documentation}

\resetcurrentobjects
\hypertarget{--doc-getting\_started}{}

\section{Installation et mise à jour de Pelican}


\subsection{Installation}

Il y a deux façons d’installer Pelican sur son système. La première est via l’utilitaire
pip, l’autre façon est de télécharger Pelican via Github. Ici nous allons voir les deux
façons de procéder.


\subsubsection{Via pip}

Pour installer Pelican via pip, vous aurez besoin du paquet python-pip. puis installez Pelican

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c}{\PYGZsh{} apt-get install python-pip}
\PYG{c}{\PYGZsh{} pip install pelican}
\end{Verbatim}


\subsubsection{Via Github}

Pour installer Pelican en reprenant le code via Github, nous aurons besoin du paquet
git-core pour récupérez les sources de Pelican. Puis nous procédons à l’installation

\begin{Verbatim}[commandchars=@\[\]]
@# apt-get install git-core
@$ git clone https://github.com/ametaireau/pelican.git
@$ cd pelican
@# python setup.py install
\end{Verbatim}


\subsection{Mises à jour}


\subsubsection{Via pip}

Rien de bien compliqué pour mettre à jour via pip

\begin{Verbatim}[commandchars=@\[\]]
@$ cd votreRepertoireSource
@$ pip install --upgrade pelican
\end{Verbatim}


\subsubsection{Via Github}

C'est un peu plus long avec Github par contre

\begin{Verbatim}[commandchars=@\[\]]
@$ cd votreRepertoireSource
@$ git pull origin master
@$ cd pelican
@# python setup.py install
\end{Verbatim}

Vous aurez un message d’erreur si le module setuptools de python n’est pas installé.
La manipulation est la suivante

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c}{\PYGZsh{} apt-get install python-setuptools}
\end{Verbatim}


\subsection{Alors, quelle méthode choisir ?}

Vous avez le choix entre deux méthodes, mais aussi entre deux concepts. La méthode
de Github est la version de développement, où les modifications arrivent assez
fréquemment sans être testées à fond. La version de pip est une version arrêtée avec un
numéro de version dans laquelle vous aurez moins de bug. N’oubliez cependant pas
que le projet est très jeune et manque donc de maturité. Si vous aimez avoir les toutes
dernières versions utilisez Github, sinon penchez vous sur pip.

\resetcurrentobjects
\hypertarget{--doc-settings}{}

\section{Settings}


\subsection{Specifying the settings}

Pelican is configurable thanks to a configuration file, that you can pass to
the command line:

\begin{Verbatim}[commandchars=@\[\]]
@$ pelican -s path/to/your/settingsfile.py path
\end{Verbatim}

Settings are given as the form of a python module (a file). You can have an
example by looking at \href{https://github.com/ametaireau/pelican/raw/master/samples/pelican.conf.py}{/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.

\begin{tabulary}{\textwidth}{|L|L|}
\hline
\textbf{
Setting name
} & \textbf{
what it does ?
}\\
\hline

\emph{AUTHOR}
 & 
Default author (put your name)
\\

\emph{CATEGORY\_FEED}
 & 
Where to put the atom categories feeds. default is
\emph{feeds/\%s.atom.xml}, where \%s is the name of the
category.
\\

\emph{CATEGORY\_FEED\_RSS}
 & 
Where to put the categories rss feeds. default is None
(no rss)
\\

\emph{CSS\_FILE}
 & 
To specify the CSS file you want to load, if it's not
the default one (`main.css')
\\

\emph{DEFAULT\_CATEGORY}
 & 
The default category to fallback on. \emph{misc} by default.
\\

\emph{DEFAULT\_LANG}
 & 
The default language to use. Default is `en'.
\\

\emph{DISPLAY\_PAGES\_ON\_MENU}
 & 
Display or not the pages on the menu of the template.
Templates can follow or not this settings.
\\

\emph{FALLBACK\_ON\_FS\_DATE}
 & 
If True, pelican will use the file system dates infos
(mtime) if it can't get informations from the
metadata?
\\

\emph{FEED}
 & 
relative url to output the atom feed. Default is
\emph{feeds/all.atom.xml}
\\

\emph{FEED\_RSS}
 & 
relative url to output the rss feed. Default is
None (no rss)
\\

\emph{JINJA\_EXTENSIONS}
 & 
A list of any Jinja2 extensions you want to use.
Default is no extensions (the empty list).
\\

\emph{KEEP\_OUTPUT\_DIRECTORY}
 & 
Keep the output directory and just update all the generated files.
Default is to delete the output directory.
\\

\emph{MARKUP}
 & 
A list of available markup languages you want to use.
For the moment, only available values are \emph{rst} and \emph{md}.
\\

\emph{OUTPUT\_PATH}
 & 
Where to output the generated files. Default to
``output''
\\

\emph{PATH}
 & 
path to look at for input files.
\\

\emph{PDF\_PROCESSOR}
 & 
Put True if you want to have PDF versions of your
documents. You will need to install \emph{rst2pdf}.
\\

\emph{REVERSE\_ARCHIVE\_ORDER}
 & 
Reverse the archives order. (True makes it in
descending order: the newer first)
\\

\emph{SITEURL}
 & 
base URL of your website.
\\

\emph{SITENAME}
 & 
Your site name,
\\

\emph{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.
\\

\emph{STATIC\_THEME\_PATHS}
 & 
Static theme paths you want to copy. Default values
is \emph{static}, but if your theme have others static paths,
you can put them here.
\\

\emph{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)
\\

\emph{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.
\\
\hline
\end{tabulary}



\subsection{Themes}

3 themes are available. You can specify them using the \emph{-t} option:
\begin{itemize}
\item {} 
notmyidea

\item {} 
simple (a synonym for ``full text'' :)

\item {} 
martyalchin

\end{itemize}

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 \href{http://alexis.notmyidea.org/pelican/themes.html}{a guide on how to create your theme}

The \emph{notmyidea} theme can make good use of the following settings. I recommend
to use them too in your themes.

\begin{tabulary}{\textwidth}{|L|L|}
\hline
\textbf{
Setting name
} & \textbf{
what it does ?
}\\
\hline

\emph{DISQUS\_SITENAME}
 & 
Pelican can handle disqus comments, specify the
sitename you've filled in on disqus
\\

\emph{GITHUB\_URL}
 & 
Your github URL (if you have one), it will then
use it to create a github ribbon.
\\

\emph{GOOGLE\_ANALYTICS}
 & 
`UA-XXXX-YYYY' to activate google analytics.
\\

\emph{LINKS}
 & 
A list of tuples (Title, Url) for links to appear on
the header.
\\

\emph{SOCIAL}
 & 
A list of tuples (Title, Url) to appear in the ``social''
section.
\\

\emph{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.
\\
\hline
\end{tabulary}


In addition, you can use the ``wide'' version of the \emph{notmyidea} theme, by
adding that in your configuration:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{CSS\PYGZus{}FILE} \PYG{o}{=} \PYG{l+s}{"}\PYG{l+s}{wide.css}\PYG{l+s}{"}
\end{Verbatim}

\resetcurrentobjects
\hypertarget{--doc-themes}{}

\hypertarget{theming-pelican}{}\section{How to create themes for pelican}

Pelican uses the great \href{http://jinjna.pocoo.org}{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 \href{https://github.com/ametaireau/pelican/tree/master/pelican/themes/simple/templates}{here}


\subsection{Structure}

To make your own theme, you must follow the following structure:

\begin{Verbatim}[commandchars=@\[\]]
├-- static
@textbar[]   ├-- css
@textbar[]   └-- 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.
\end{Verbatim}
\begin{itemize}
\item {} 
\emph{static} contains all the static content. It will be copied on the output
\emph{theme/static} folder then. I've put the css and image folders, but they are
just examples. Put what you need here.

\item {} 
\emph{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.

\end{itemize}


\subsection{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.


\subsubsection{Common variables}

All of those settings will be given to all templates.

\begin{tabulary}{\textwidth}{|L|L|}
\hline
\textbf{
Variable
} & \textbf{
Description
}\\
\hline

articles
 & 
That's the list of articles, ordsered desc. by date
all the elements are \emph{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
\\
\hline
\end{tabulary}



\subsubsection{category.html}

This template will be processed for each of the existing categories, and will
finally remain at output/category/\emph{category\_name}.html.

\begin{tabulary}{\textwidth}{|L|L|}
\hline
\textbf{
Variable
} & \textbf{
Description
}\\
\hline

articles
 & 
The articles of this category
\\

category
 & 
The name of the category being processed
\\
\hline
\end{tabulary}



\subsubsection{article.html}

This template will be processed for each article. .html files will be outputed
in output/\emph{article\_name}.html. Here are the specific variables it gets.

\begin{tabulary}{\textwidth}{|L|L|}
\hline
\textbf{
Variable
} & \textbf{
Description
}\\
\hline

article
 & 
The article object to be displayed
\\

category
 & 
The name of the category of the current article
\\
\hline
\end{tabulary}



\subsubsection{tag.html}

For each tag, this template will be processed. It will create .html files in
/output/tag/\emph{tag\_name}.html

\begin{tabulary}{\textwidth}{|L|L|}
\hline
\textbf{
Variable
} & \textbf{
Description
}\\
\hline

tag
 & 
The name of the tag being processed
\\

articles
 & 
Articles related to this tag
\\
\hline
\end{tabulary}


\resetcurrentobjects
\hypertarget{--doc-internals}{}

\section{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 :)


\subsection{Overall structure}

What \emph{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:
\begin{itemize}
\item {} 
\emph{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.

\item {} 
\emph{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)

\item {} 
\emph{generators} generate the different outputs. For instance, pelican comes with
\emph{ArticlesGenerator} and \emph{PageGenerator}, into others. Given
a configurations, they can do whatever they want. Most of the time it's
generating files from inputs.

\item {} 
\emph{pelican} also uses \emph{templates}, so it's easy to write you own theme. The
syntax is \emph{jinja2}, and, trust me, really easy to learn, so don't hesitate
a second.

\end{itemize}


\subsection{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 \emph{read}
method, that is returning an HTML content and some metadata.

Take a look to the Markdown reader:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{class} \PYG{n+nc}{MarkdownReader}\PYG{p}{(}\PYG{n+nb}{object}\PYG{p}{)}\PYG{p}{:}

    \PYG{k}{def} \PYG{n+nf}{read}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{,} \PYG{n}{filename}\PYG{p}{)}\PYG{p}{:}
        \PYG{l+s+sd}{"""Parse content and metadata of markdown files"""}
        \PYG{n}{text} \PYG{o}{=} \PYG{n+nb}{open}\PYG{p}{(}\PYG{n}{filename}\PYG{p}{)}
        \PYG{n}{md} \PYG{o}{=} \PYG{n}{Markdown}\PYG{p}{(}\PYG{n}{extensions} \PYG{o}{=} \PYG{p}{[}\PYG{l+s}{'}\PYG{l+s}{meta}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{codehilite}\PYG{l+s}{'}\PYG{p}{]}\PYG{p}{)}
        \PYG{n}{content} \PYG{o}{=} \PYG{n}{md}\PYG{o}{.}\PYG{n}{convert}\PYG{p}{(}\PYG{n}{text}\PYG{p}{)}

        \PYG{n}{metadatas} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{p}{\PYGZcb{}}
        \PYG{k}{for} \PYG{n}{name}\PYG{p}{,} \PYG{n}{value} \PYG{o+ow}{in} \PYG{n}{md}\PYG{o}{.}\PYG{n}{Meta}\PYG{o}{.}\PYG{n}{items}\PYG{p}{(}\PYG{p}{)}\PYG{p}{:}
            \PYG{k}{if} \PYG{n}{name} \PYG{o+ow}{in} \PYG{n}{\PYGZus{}METADATAS\PYGZus{}FIELDS}\PYG{p}{:}
                \PYG{n}{meta} \PYG{o}{=} \PYG{n}{\PYGZus{}METADATAS\PYGZus{}FIELDS}\PYG{p}{[}\PYG{n}{name}\PYG{p}{]}\PYG{p}{(}\PYG{n}{value}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{)}
            \PYG{k}{else}\PYG{p}{:}
                \PYG{n}{meta} \PYG{o}{=} \PYG{n}{value}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}
            \PYG{n}{metadatas}\PYG{p}{[}\PYG{n}{name}\PYG{o}{.}\PYG{n}{lower}\PYG{p}{(}\PYG{p}{)}\PYG{p}{]} \PYG{o}{=} \PYG{n}{meta}
        \PYG{k}{return} \PYG{n}{content}\PYG{p}{,} \PYG{n}{metadatas}
\end{Verbatim}

Simple isn't it ?


\subsection{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.
\begin{itemize}
\item {} 
\emph{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 \emph{PageGenerator} \emph{generate\_context} method find
all the pages, transform them into objects, and populate the context with
them. Be careful to \emph{not} output anything using this context at this stage,
as it is likely to change by the effect of others generators.

\item {} 
\emph{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 \emph{writer} object, that is passed at the first
argument of this function. In the \emph{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 \emph{write\_file}) for each page encountered.

\end{itemize}

\resetcurrentobjects
\hypertarget{--doc-faq}{}

\section{Frequently Asked Questions (FAQ)}

Here is a summary of the frequently asked questions for pelican.


\subsection{Is it mandatory to have a configuration file ?}

No, it's not. Configurations files are just an easy way to configure pelican.
For the basic operations, it's possible to specify options while invoking
pelican with the command line (see \emph{pelican --help} for more informations about
that)


\subsection{I'm creating my own theme, how to use pygments ?}

Pygment add some classes to the generated content, so the theming of your theme
will be done thanks to a css file. You can have a look to the one proposed by
default \href{http://pygments.org/demo/15101/}{on the project website}


\subsection{How do I create my own theme ?}

Please refer yourself to \hyperlink{theming-pelican}{\emph{How to create themes for pelican}}.


\subsection{How can I help ?}

You have different options to help. First, you can use pelican, and report any
idea or problem you have on \href{http://github.com/ametaireau/pelican/issues}{the bugtracker}.

If you want to contribute, please have a look to \href{https://github.com/ametaireau/pelican/}{the git repository}, fork it, add your changes and do
a pull request, I'll review them as soon as possible.

You can also contribute by creating themes, and making the documentation
better.


\renewcommand{\indexname}{Module Index}
\printmodindex
\renewcommand{\indexname}{Index}
\printindex
\end{document}