diff --git a/.gitignore b/.gitignore index 721af351..5bb92c09 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,5 @@ docs/fr/_build build dist output +tags +.tox diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000..823c1172 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,13 @@ +language: python +python: + - "2.6" + - "2.7" +install: + - pip install nose unittest2 mock --use-mirrors + - pip install . --use-mirrors +script: nosetests -s tests +notifications: + irc: + channels: + - "irc.freenode.org#pelican" + on_success: change diff --git a/CHANGELOG b/CHANGELOG new file mode 100644 index 00000000..46aa68a5 --- /dev/null +++ b/CHANGELOG @@ -0,0 +1,100 @@ +X.X + +* Refactored the way URL are handled. +* Improved the english documentation +* Fixed packaging using setuptools entrypoints +* Added typogrify support +* Added a way to disable feed generation + +2.8 + +* dotclear importer +* Allow the usage of markdown extensions +* Themes are now easily extensible +* Don't output pagination information if there is only one page. +* Add a page per author, with all their articles +* Improved the test suite +* Made the themes more easy to extend +* Removed Skribit support +* Added a "pelican-quickstart" script +* Fixed timezone-related issues +* Add some scripts for windows support +* Date can be specified in seconds +* Never fail when generating posts (skip and continue) +* Allow the use of future dates +* Support having different timezones per languages. +* Enhanced the documentation + +2.7 + +* Uses logging rather than echoing to stdout +* Support custom jinja filters +* Compatibility with python 2.5 +* Add a theme manager +* Packaged for debian +* Add draft support + +2.6 + +* changes in the output directory structure +* makes templates easier to work with / create +* Add RSS support (was only atom previously) +* Add tag support for the feeds +* Enhance the documentation +* Add another theme (brownstone) +* Add translations +* Add a way to use "cleaner urls" with a rewrite url module (or equivalent) +* Add a tag cloud +* Add an autoreloading feature: the blog is automatically regenerated each time a modification is detected +* Translate the documentation in french +* import a blog from an rss feed +* Pagination support +* Add skribit support + +2.5 + +* import from wordpress +* add some new themes (martyalchin / wide-notmyidea) +* first bug report ! +* linkedin support +* added a FAQ +* google analytics support +* twitter support +* use relative urls not static ones + +2.4 + +* minor themes changes +* add disqus support (so we have comments) +* another code refactoring +* add config settings about pages +* blog entries can also be generated in pdf + +2.3 + +* markdown support + +2.2 + +* Prettify output +* Manages static pages as well + +2.1 + +* Put the notmyidea theme by default + +2.0 + +* Refactoring to be more extensible +* Change into the setting variables + +1.2 + +* Add a debug option +* Add feeds per category +* Use filsystem to get dates if no metadata provided +* Add pygment support + +1.1: + +* first working version diff --git a/MANIFEST.in b/MANIFEST.in index 996b1814..a092ecd0 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,3 +1,4 @@ include *.rst +global-include *.py recursive-include pelican *.html *.css *png include LICENSE diff --git a/README.rst b/README.rst index 8a6ef04c..5012bb9c 100644 --- a/README.rst +++ b/README.rst @@ -1,53 +1,59 @@ Pelican ####### +.. image:: https://secure.travis-ci.org/ametaireau/pelican.png?branch=master + Pelican is a simple weblog generator, written in `Python `_. -* Write your weblog entries directly with your editor of choice (vim!) and - directly in `reStructuredText `_, or `Markdown `_. -* A simple cli-tool to (re)generate the weblog. +* Write your weblog entries directly with your editor of choice (vim!) + in `reStructuredText `_ or `Markdown `_ +* Includes a simple CLI tool to (re)generate the weblog * Easy to interface with DVCSes and web hooks -* Completely static output, so easy to host anywhere ! +* Completely static output is easy to host anywhere Features -------- Pelican currently supports: -* blog articles and pages -* comments, via an external service (disqus). Please notice that while - it's useful, it's an external service, and you'll not manage the - comments by yourself. It could potentially eat your data. -* theming support (themes are done using `jinja2 `_) -* PDF generation of the articles/pages (optional). -* Translations -* Syntactic recognition +* Blog articles and pages +* Comments, via an external service (Disqus). (Please note that while + useful, Disqus is an external service, and thus the comment data will be + somewhat outside of your control and potentially subject to data loss.) +* Theming support (themes are created using `jinja2 `_) +* PDF generation of the articles/pages (optional) +* Publication of articles in multiple languages +* Atom/RSS feeds +* Code syntax highlighting +* Import from WordPress, Dotclear, or RSS feeds +* Integration with external tools: Twitter, Google Analytics, etc. (optional) -Have a look to `the documentation `_ for -more informations. +Have a look at `the documentation `_ for +more information. -Why the name "Pelican" ? +Why the name "Pelican"? ------------------------ -Heh, you didn't noticed? "Pelican" is an anagram for "Calepin" ;) +Heh, you didn't notice? "Pelican" is an anagram for « Calepin » ;) Source code ----------- -You can access the source code via git on http://github.com/ametaireau/pelican/ +You can access the source code via git at: https://github.com/ametaireau/pelican -If you feel hackish, have a look to the `pelican's internals explanations -`_. +If you feel hackish, have a look at the explanation of `Pelican's internals +`_. Feedback / Contact us -===================== +--------------------- -If you want to see new features in Pelican, dont hesitate to tell me, to clone -the repository, etc. That's open source, dude! +If you want to see new features in Pelican, don't hesitate to offer suggestions, +clone the repository, etc. There are many ways to `contribute +`_. That's open source, dude! Contact me at "alexis at notmyidea dot org" for any request/feedback! You can also join the team at `#pelican on irc.freenode.org `_ -(or if you don't have any IRC client, using `the webchat +(or if you don't have any IRC client, use `the webchat `_) for quick feedback. diff --git a/THANKS b/THANKS index 39f54e61..2a20100e 100644 --- a/THANKS +++ b/THANKS @@ -16,3 +16,4 @@ bugs or giving ideas. Thanks to them ! - Marcus Fredriksson - Günter Kolousek - Simon Liedtke +- Manuel F. Viera diff --git a/TODO b/TODO index 9928ced2..ca29204d 100644 --- a/TODO +++ b/TODO @@ -1,8 +1,9 @@ * Add a way to support pictures (see how sphinx makes that) -* Find a way to extend the existing templates instead of rewriting all from scratch. * Make the program support UTF8-encoded files as input (and later: any encoding?) * Add status support (draft, published, hidden) * Add a serve + automatic generation behaviour. * Recompile only the changed files, not all. * Add a way to make the coffee (or not) * Add a sitemap generator. +* read templates from the templates folder per default +* add support of github via ghg import diff --git a/bin/pelican b/bin/pelican deleted file mode 100755 index 3fe2ee57..00000000 --- a/bin/pelican +++ /dev/null @@ -1,3 +0,0 @@ -#!/usr/bin/env python -from pelican import main -main() diff --git a/dev_requirements.txt b/dev_requirements.txt index acafebc0..c7f53682 100644 --- a/dev_requirements.txt +++ b/dev_requirements.txt @@ -1,5 +1,7 @@ -Jinja2==2.5.5 -Pygments==1.4 -docutils==0.7 -feedgenerator==1.2.1 +Jinja2 +Pygments +docutils +feedgenerator unittest2 +pytz +mock diff --git a/docs/_static/overall.png b/docs/_static/overall.png new file mode 100644 index 00000000..1240a148 Binary files /dev/null and b/docs/_static/overall.png differ diff --git a/docs/_static/theme-basic.zip b/docs/_static/theme-basic.zip new file mode 100644 index 00000000..d1e4754a Binary files /dev/null and b/docs/_static/theme-basic.zip differ diff --git a/docs/_static/uml.jpg b/docs/_static/uml.jpg new file mode 100644 index 00000000..03655d7e Binary files /dev/null and b/docs/_static/uml.jpg differ diff --git a/docs/conf.py b/docs/conf.py index 3cd6c061..ac2d67ee 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,6 +1,10 @@ # -*- coding: utf-8 -*- import sys, os +sys.path.append(os.path.abspath('..')) + +from pelican import __version__, __major__ + # -- General configuration ----------------------------------------------------- templates_path = ['_templates'] extensions = ['sphinx.ext.autodoc',] @@ -9,12 +13,11 @@ master_doc = 'index' project = u'Pelican' copyright = u'2010, Alexis Metaireau and contributors' exclude_patterns = ['_build'] -version = "2" -release = version +version = __version__ +release = __major__ # -- Options for HTML output --------------------------------------------------- -sys.path.append(os.path.abspath('_themes')) html_theme_path = ['_themes'] html_theme = 'pelican' @@ -40,7 +43,7 @@ man_pages = [ ('index', 'pelican', u'pelican documentation', [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') + [u'Mickaël Raybaud'], 1), + ('themes', 'pelican-theming', u'How to create themes for Pelican', + [u'The Pelican contributors'], 1) ] diff --git a/docs/contribute.rst b/docs/contribute.rst index 02af695f..fcf8d5c0 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -1,39 +1,49 @@ -How to contribute ? +How to contribute? ################### -There are many ways to contribute to pelican. You can enhance the -documentation, add missing features, fix bugs or just report them. +There are many ways to contribute to Pelican. You can enhance the +documentation, add missing features, and fix bugs (or just report them). -Don't hesitate to fork and make a pull request on github. +Don't hesitate to fork and make a pull request on GitHub. -Set up the development environment -================================== +Setting up the development environment +====================================== -You're free to setup up the environment in any way you like. Here is a way -using virtualenv and virtualenvwrapper. If you don't have them, you can install -them using:: +You're free to set up your development environment any way you like. Here is a +way using virtualenv and virtualenvwrapper. If you don't have them, you can +install these packages via:: $ pip install virtualenvwrapper -Virtual environments allow you to work on an installation of python which is -not the one installed on your system. Especially, it will install the different -projects under a different location. +Virtual environments allow you to work on Python projects which are isolated +from one another so you can use different packages (and package versions) with +different projects. -To create the virtualenv environment, you have to do:: +To create a virtual environment, use the following syntax:: - $ mkvirtualenv pelican --no-site-package + $ mkvirtualenv pelican -Then you would have to install all the dependencies:: +To manually install the dependencies:: $ pip install -r dev_requirements.txt + $ python setup.py develop Running the test suite ====================== Each time you add a feature, there are two things to do regarding tests: -checking that the tests run in a right way, and be sure that you add tests for -the feature you are working on or the bug you're fixing. +checking that the existing tests pass, and adding tests for your new feature +or for the bug you're fixing. -The tests leaves under "pelican/tests" and you can run them using the +The tests live in "pelican/tests" and you can run them using the "discover" feature of unittest2:: $ unit2 discover + +Coding standards +================ + +Try to respect what is described in the PEP8 +(http://www.python.org/dev/peps/pep-0008/) when providing patches. This can be +eased by the pep8 tool (http://pypi.python.org/pypi/pep8) or by Flake8, which +will give you some other cool hints about what's good or wrong +(http://pypi.python.org/pypi/flake8/) diff --git a/docs/faq.rst b/docs/faq.rst index bee1dd54..b3dbca87 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -1,38 +1,51 @@ Frequently Asked Questions (FAQ) ################################ -Here is a summary of the frequently asked questions for pelican. +Here is a summary of the frequently asked questions for Pelican. -Is it mandatory to have a configuration file ? -============================================== +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 `pelican --help` for more informations about -that) +No, it's not. Configuration files are just an easy way to configure Pelican. +For basic operations, it's possible to specify options while invoking Pelican +via the command line. See `pelican --help` for more information. -I'm creating my own theme, how to use pygments ? -================================================ +I'm creating my own theme. How do I use Pygments for syntax highlighting? +========================================================================= -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 `on the project website `_ +Pygments adds some classes to the generated content. These classes are used by +themes to style code syntax highlighting via CSS. Specifically, you can +customize the appearance of your syntax highlighting via the `.codehilite pre` +class in your theme's CSS file. To see how various styles can be used to render +Django code, for example, you can use the demo `on the project website +`_. -How do I create my own theme ? +How do I create my own theme? ============================== -Please refer yourself to :ref:`theming-pelican`. +Please refer to :ref:`theming-pelican`. -How can I help ? +How can I help? ================ -You have different options to help. First, you can use pelican, and report any -idea or problem you have on `the bugtracker +There are several ways to help out. First, you can use Pelican and report any +suggestions or problems you might have on `the bugtracker `_. -If you want to contribute, please have a look to `the git repository -`_, fork it, add your changes and do -a pull request, I'll review them as soon as possible. +If you want to contribute, please fork `the git repository +`_, make your changes, and issue +a pull request. I'll review your changes as soon as possible. -You can also contribute by creating themes, and making the documentation -better. +You can also contribute by creating themes and improving the documentation. + +I want to use Markdown, but I got an error. +=========================================== + +Markdown is not a hard dependency for Pelican, so you will need to explicitly +install it. You can do so by typing:: + + $ (sudo) pip install markdown + +In case you don't have pip installed, consider installing it via:: + + $ (sudo) easy_install pip diff --git a/docs/fr/index.rst b/docs/fr/index.rst index dca85fac..9fd0c0f0 100644 --- a/docs/fr/index.rst +++ b/docs/fr/index.rst @@ -54,3 +54,4 @@ Documentation parametres_article astuces faq + pelican-themes diff --git a/docs/fr/themes.rst b/docs/fr/themes.rst index 53e6374e..c6f45300 100644 --- a/docs/fr/themes.rst +++ b/docs/fr/themes.rst @@ -169,19 +169,3 @@ dates_pages La page actuelle d'articles, ordonnée par date croissante. page_name 'tag/`nom du tag`'. =================== =================================================== - -Inclure le script skribit -========================= - -Pour pouvoir supporter les scripts skribit dans vos thèmes, vous devez -faire ceci : - - * Copier `skribit_tab_script.html` et `skribit_widget_script.html` dans - votre dossier de templates. - * Ajouter {% include 'skribit_tab_script' %} dans votre pour - ajouter le support de l'onglet de suggestions. - * Ajouter {% include 'skribit_widget_script' %} là où vous le souhaitez - pour ajouter le widget dans la sidebar. - -Vous pouvez regarder le thème par défault (notmyidea) pour voir un -exemple de thème fonctionnel. diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 2187dbb9..1647fee4 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -4,45 +4,44 @@ Getting started Installing ========== -You're ready? Let's go ! You can install pelican in a lot of different ways, -the simpler one is via `pip `_:: +You're ready? Let's go! You can install Pelican via several different methods. The simplest is via `pip `_:: $ pip install pelican -If you have the sources, you can install pelican using the distutils command -install. I recommend to do so in a virtualenv:: +If you have the project source, you can install Pelican using the distutils +method. I recommend doing so in a virtualenv:: - $ virtualenv . + $ virtualenv pelican_venv $ source bin/activate $ python setup.py install Dependencies ------------ -At this time, pelican is dependent of the following python packages: +At this time, Pelican is dependent on the following Python packages: -* feedgenerator, to generate the ATOM feeds. -* jinja2, for templating support. +* feedgenerator, to generate the Atom feeds +* jinja2, for templating support -If you're not using python 2.7, you will also need `argparse`. +If you're not using Python 2.7, you will also need `argparse`. Optionally: -* docutils, for reST support -* pygments, to have syntactic colorization with resT input -* Markdown, for Markdown as an input format +* pygments, for syntax highlighting +* docutils, for supporting reStructuredText as an input format +* Markdown, for supporting Markdown as an input format -Writing articles using pelican +Writing articles using Pelican ============================== -Files metadata +File metadata -------------- -Pelican tries to be smart enough to get the informations it needs from the -file system (for instance, about the category of your articles), but you need to -provide by hand some of those informations in your files. +Pelican tries to be smart enough to get the information it needs from the +file system (for instance, about the category of your articles), but some +information you need to provide in the form of metadata inside your files. -You could provide the metadata in the restructured text files, using the +You can provide this metadata in reStructuredText text files via the following syntax (give your file the `.rst` extension):: My super title @@ -54,35 +53,46 @@ following syntax (give your file the `.rst` extension):: :author: Alexis Metaireau -You can also use a markdown syntax (with a file ending in `.md`):: +You can also use Markdown syntax (with a file ending in `.md`):: Date: 2010-12-03 Title: My super title + Tags: thats, awesome + Slug: my-super-post - Put you content here. + This is the content of my super blog post. -Note that none of those are mandatory: if the date is not specified, pelican will -rely on the mtime of your file, and the category can also be determined by the -directory where the rst file is. For instance, the category of -`python/foobar/myfoobar.rst` is `foobar`. +Note that, aside from the title, none of this metadata is mandatory: if the date +is not specified, Pelican will rely on the file's "mtime" timestamp, and the +category can be determined by the directory in which the file resides. For +example, a file located at `python/foobar/myfoobar.rst` will have a category of +`foobar`. Generate your blog ------------------ -To launch pelican, just use the `pelican` command:: +To launch Pelican, just use the `pelican` command:: $ pelican /path/to/your/content/ [-s path/to/your/settings.py] -And… that's all! You can see your weblog generated on the `content/` folder. +And… that's all! Your weblog will be generated and saved in the `content/` +folder. -This one will just generate a simple output, with the default theme. It's not -really sexy, as it's a simple HTML output (without any style). +The above command will use the default theme to produce a simple site. It's not +very sexy, as it's just simple HTML output (without any style). -You can create your own style if you want, have a look to the help to see all +You can create your own style if you want. Have a look at the help to see all the options you can use:: $ pelican --help +Kickstart a blog +---------------- + +You also can use the `pelican-quickstart` script to start a new blog in +seconds, by just answering few questions. Just run `pelican-quickstart` and +you're done! (Added in Pelican 3.0) + Pages ----- @@ -95,34 +105,26 @@ the menu. Importing an existing blog -------------------------- -It is possible to import wordpress themes and RSS themes using a script which -is living in `tools`: importer. - -You can call it this way for a wordpress import:: - - $ python importer.py --wpfile /your/wordpress/export -o output_dir - -And like this for an import from an RSS feed:: - - $ python importer.py --feed http://your/rss/feed -o output_dir +It is possible to import your blog from Dotclear, WordPress, and RSS feeds using +a simple script. See :ref:`import`. Translations ------------ It is possible to translate articles. To do so, you need to add a `lang` meta -in your articles/pages, and to set a `DEFAULT_LANG` setting (which is en by -default). -Then, only articles with this default language will be listed, and -each article will have a translation list. +attribute to your articles/pages and set a `DEFAULT_LANG` setting (which is +English [en] by default). With those settings in place, only articles with the +default language will be listed, and each article will be accompanied by a list +of available translations for that article. -Pelican uses the "slug" of two articles to compare if they are translations of -each others. So it's possible to define (in restructured text) the slug -directly. +Pelican uses the article's URL "slug" to determine if two or more articles are +translations of one another. The slug can be set manually in the file's +metadata; if not set explicitly, Pelican will auto-generate the slug from the +title of the article. -Here is an exemple of two articles (one in english and the other one in -french). +Here is an example of two articles, one in English and the other in French. -The english one:: +The English article:: Foobar is not dead ################## @@ -130,9 +132,9 @@ The english one:: :slug: foobar-is-not-dead :lang: en - That's true, foobar is still alive ! + That's true, foobar is still alive! -And the french one:: +And the French version:: Foobar n'est pas mort ! ####################### @@ -142,34 +144,67 @@ And the french one:: Oui oui, foobar est toujours vivant ! -Despite the text quality, you can see that only the slug is the same here. -You're not forced to define the slug that way, and it's completely possible to -have two translations with the same title (which defines the slug) +Post content quality notwithstanding, you can see that only item in common +between the two articles is the slug, which is functioning here as an +identifier. If you'd rather not explicitly define the slug this way, you must +then instead ensure that the translated article titles are identical, since the +slug will be auto-generated from the article title. -Syntactic recognition +Syntax highlighting --------------------- -Pelican is able to regognise the syntax you are using, and to colorize the -right way your block codes. To do so, you have to use the following syntax:: +Pelican is able to provide colorized syntax highlighting for your code blocks. +To do so, you have to use the following convention for reStructuredText:: .. code-block:: identifier your code goes here -The identifier is one of the lexers available `here -`_. +For Markdown, format your code blocks thusly: + + ::identifier + your code goes here + +The specified identifier should be one that appears on the +`list of available lexers `_. + +You also can use the default `::` syntax, in which case it will be assumed +that your code is written in Python. For reStructuredText:: + + :: + + your code goes here + +For Markdown: + + :: + your code goes here Autoreload ---------- -It's possible to tell pelican to watch for your modifications, instead of -manually launching it each time you need. Use the `-r` option, or -`--autoreload`. +It's possible to tell Pelican to watch for your modifications, instead of +manually launching it every time you want to see your changes. To enable this, +run the `pelican` command with the `-r` or `--autoreload` options. Publishing drafts ----------------- -If you want to publish an article as a draft, for friends to review it for -instance, you can add a ``status: draft`` to its metadata, it will then be -available under the ``drafts`` folder, and not be listed under the index page nor -any category page. +If you want to publish an article as a draft (for friends to review before +publishing, for example), you can add a ``status: draft`` attribute to its +metadata. That article will then be output to the ``drafts`` folder and not +listed on the index page nor on any category page. + +Viewing the generated files +--------------------------- + +The files generated by Pelican are static files, so you don't actually need +anything special to see what's happening with the generated files. + +You can either use your browser to open the files on your disk:: + + $ firefox output/index.html + +Or run a simple web server using Python:: + + cd output && python -m SimpleHTTPServer diff --git a/docs/importer.rst b/docs/importer.rst new file mode 100644 index 00000000..377820af --- /dev/null +++ b/docs/importer.rst @@ -0,0 +1,57 @@ +.. _import: + +================================= + Import from other blog software +================================= + +Description +=========== + +``pelican-import`` is a command line tool for converting articles from other +software to ReStructuredText. The supported formats are: + +- WordPress XML export +- Dotclear export +- RSS/Atom feed + +The conversion from HTML to reStructuredText relies on `pandoc +`_. For Dotclear, if the source posts are +written with Markdown syntax, they will not be converted (as Pelican also +supports Markdown). + +Usage +""""" + +| pelican-import [-h] [--wpfile] [--dotclear] [--feed] [-o OUTPUT] +| [--dir-cat] +| input + +Optional arguments: +""""""""""""""""""" + + -h, --help show this help message and exit + --wpfile Wordpress XML export + --dotclear Dotclear export + --feed Feed to parse + -o OUTPUT, --output OUTPUT + Output path + --dir-cat Put files in directories with categories name + +Examples +======== + +for WordPress:: + + $ pelican-import --wpfile -o ~/output ~/posts.xml + +for Dotclear:: + + $ pelican-import --dotclear -o ~/output ~/backup.txt + +Tests +===== + +To test the module, one can use sample files: + +- for Wordpress: http://wpcandy.com/made/the-sample-post-collection +- for Dotclear: http://themes.dotaddict.org/files/public/downloads/lorem-backup.txt diff --git a/docs/index.rst b/docs/index.rst index 0e6ba583..7dbac168 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,62 +1,70 @@ Pelican ####### -Pelican is a simple weblog generator, writen in python. +Pelican is a simple weblog generator, written in Python. -* Write your weblog entries directly with your editor of choice (vim!) and - directly in restructured text, or markdown. -* A simple cli-tool to (re)generate the weblog. +* Write your weblog entries directly with your editor of choice (vim!) in + reStructuredText or Markdown +* A simple CLI tool to (re)generate the weblog * Easy to interface with DVCSes and web hooks -* Completely static output, so easy to host anywhere ! +* Completely static output is easy to host anywhere Features ======== Pelican currently supports: -* blog articles -* comments, via an external service (disqus). Please notice that while - it's useful, it's an external service, and you'll not manage the - comments by yourself. It could potentially eat your data. -* theming support (themes are done using `jinja2 `_) -* PDF generation of the articles/pages (optional). +* Blog articles and pages +* Comments, via an external service (Disqus). (Please note that while + useful, Disqus is an external service, and thus the comment data will be + somewhat outside of your control and potentially subject to data loss.) +* Theming support (themes are created using `jinja2 `_) +* PDF generation of the articles/pages (optional) +* Publication of articles in multiple languages +* Atom/RSS feeds +* Code syntax highlighting +* Import from WordPress, Dotclear, or RSS feeds +* Integration with external tools: Twitter, Google Analytics, etc. (optional) Why the name "Pelican" ? ======================== -Heh, you didn't noticed? "Pelican" is an anagram for "Calepin" ;) +Heh, you didn't notice? "Pelican" is an anagram for « Calepin » ;) Source code =========== -You can access the source code via git on http://github.com/ametaireau/pelican/ +You can access the source code via git at http://github.com/ametaireau/pelican/ Feedback / Contact us ===================== -If you want to see new features in Pelican, dont hesitate to tell me, to clone +If you want to see new features in Pelican, don't hesitate to tell me, to clone the repository, etc. That's open source, dude! Contact me at "alexis at notmyidea dot org" for any request/feedback! You can -also join the team at `#pelican on irc.freenode.org -`_ -(or if you don't have any IRC client, using `the webchat +also join the team at `#pelican on irc.freenode.org +`_ +(or if you don't have any IRC client, use `the webchat `_) for quick feedback. Documentation ============= -A french version of the documentation is available at :doc:`fr/index`. +A French version of the documentation is available at :doc:`fr/index`. .. toctree:: :maxdepth: 2 - + getting_started settings themes - pelican-themes plugins internals + pelican-themes + importer faq + tips contribute + report diff --git a/docs/internals.rst b/docs/internals.rst index 17541c0c..f0934825 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -1,44 +1,48 @@ 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 :) +This section describe how Pelican works internally. As you'll see, it's +quite simple, but a bit of documentation doesn't hurt. :) + +You can also find in the :doc:`report` section an excerpt of a report the +original author wrote with some software design information. + +.. _report: :doc:`report` 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. +What `pelican` does is take a list of files and process them into some +sort of output. Usually, the input files are reStructuredText and Markdown +files, and the output is a blog, but both input and output can be anything you +want. -I've separated the logic in different classes and concepts: +The logic is separated into 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. +* `writers` are responsible for writing files: .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) +* `readers` are used to read from various formats (Markdown and + reStructuredText for now, but the system is extensible). Given a file, they return + metadata (author, tags, category, etc.) and content (HTML-formatted). -* `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. +* `generators` generate the different outputs. For instance, Pelican comes with + `ArticlesGenerator` and `PageGenerator`. Given a configuration, 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 +* `pelican` also uses `templates`, so it's easy to write your own theme. The syntax is `jinja2`, and, trust me, really easy to learn, so don't hesitate - a second. + to jump in and build your own theme. -How to implement a new reader ? -=============================== +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. +Is there an awesome markup language you want to add to Pelican? +Well, the only thing you have to do is to create a class with a `read` +method that returns HTML content and some metadata. -Take a look to the Markdown reader:: +Take a look at the Markdown reader:: class MarkdownReader(Reader): enabled = bool(Markdown) @@ -58,31 +62,31 @@ Take a look to the Markdown reader:: metadata[name.lower()] = meta return content, metadata -Simple isn't it ? +Simple, isn't it? -If your new reader requires additional Python dependencies then you should wrap -their `import` statements in `try...except`. Then inside the reader's class -set the `enabled` class attribute to mark import success or failure. This makes -it possible for users to continue using their favourite markup method without -needing to install modules for all the additional formats they don't use. +If your new reader requires additional Python dependencies, then you should wrap +their `import` statements in a `try...except` block. Then inside the reader's +class, set the `enabled` class attribute to mark import success or failure. +This makes it possible for users to continue using their favourite markup method +without needing to install modules for formats they don't use. -How to implement a new generator ? -================================== +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. +Generators have 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. +* `generate_context`, that is called first, 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. + templates. For instance, the `PageGenerator` `generate_context` method finds + all the pages, transforms them into objects, and populates the context with + them. Be careful *not* to output anything using this context at this stage, + as it is likely to change by the effect of other 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 +* `generate_output` is then called. And guess what is it made for? Oh, + generating the output. :) It's here that you may want to look at the context + and call the methods of the `writer` object that is passed as 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 + 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/pelican-themes.rst b/docs/pelican-themes.rst index bd2dba77..c7cbc5b7 100644 --- a/docs/pelican-themes.rst +++ b/docs/pelican-themes.rst @@ -57,11 +57,11 @@ With ``pelican-themes``, you can see the available themes by using the ``-l`` or two-column@ simple -In this example, we can see there is 3 themes available: ``notmyidea``, ``simple`` and ``two-column``. +In this example, we can see there are three 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). +``two-column`` is prefixed with an ``@`` because this theme is not copied to the Pelican theme path, but is instead 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: +Note that you can combine the ``--list`` option with the ``-v`` or ``--verbose`` option to get more verbose output, like this: .. code-block:: console @@ -95,8 +95,8 @@ This option takes as argument the path(s) of the theme(s) you want to install, a 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. +The ``pelican-themes`` command can also remove themes from the Pelican themes path. +The ``-r`` or ``--remove`` option 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 @@ -113,7 +113,7 @@ The ``-r`` or ``--remove`` takes as argument the name(s) of the theme(s) you wan Creating symbolic links """"""""""""""""""""""" -``pelican-themes`` can also install themes by creating symbolic links instead of copying the whole themes in the Pelican themes path. +``pelican-themes`` can also install themes by creating symbolic links instead of copying entire themes into the Pelican themes path. To symbolically link a theme, you can use the ``-s`` or ``--symlink``, which works exactly as the ``--install`` option: @@ -152,7 +152,7 @@ The ``--install``, ``--remove`` and ``--symlink`` option are not mutually exclus --symlink ~/Dev/Python/pelican-themes/two-column \ --verbose -In this example, the theme ``notmyidea-cms`` is replaced by the theme ``notmyidea-cms-fr`` +In this example, the theme ``notmyidea-cms`` is replaced by the theme ``notmyidea-cms-fr`` diff --git a/docs/plugins.rst b/docs/plugins.rst index 3bf7c532..db5a4bfc 100644 --- a/docs/plugins.rst +++ b/docs/plugins.rst @@ -3,17 +3,18 @@ Plugins ####### -Since version 2.8, pelican manages plugins. Plugins are a way to add feature to -pelican without having to directly hack pelican code. +Since version 3.0, pelican manages plugins. Plugins are a way to add features +to pelican without having to directly hack pelican code. Pelican is shipped with a set of core plugins, but you can easily implement -your own (and this page describes how) +your own (and this page describes how). How to use plugins? ==================== -To load plugins, you have to specify a them in your settings file. You have two -ways to do so: by specifying strings with the path to the callables: :: +To load plugins, you have to specify them in your settings file. You have two +ways to do so. +Either by specifying strings with the path to the callables:: PLUGINS = ['pelican.plugins.gravatar',] @@ -76,28 +77,18 @@ Translation ----------- Github Activity -_______________ +--------------- -This plugins introduces a new depencency, you have to install feedparser -if you want to use it, these are some ways to do it:: +This plugin makes use of the ``feedparser`` library that you'll need to +install. - apt-get install python-feedparser # on debian based distributions like ubuntu - sudo easy_install feedparser - sudo pip install feedparser - -To enable it set in your pelican config file the GITHUB_ACTIVITY_FEED -parameter pointing to your github activity feed. - -for example my personal activity feed is:: - - https://github.com/kpanic.atom - -and the config line could be:: +Set the GITHUB_ACTIVITY_FEED parameter to your github activity feed. +For example, my setting would look like:: GITHUB_ACTIVITY_FEED = 'https://github.com/kpanic.atom' -in your template just write a for in jinja2 syntax against the -github_activity variable, like for example:: +On the templates side, you just have to iterate over the ``github_activity`` +variable, as in the example:: {% if GITHUB_ACTIVITY_FEED %}