github/pelican
1
0
Fork 1
mirror of https://github.com/getpelican/pelican.git synced 2025-10-15 20:28:56 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update the documentation.

Browse source
This commit is contained in:
Alexis Metaireau 2010-12-14 15:31:11 +00:00
commit e0e62d8b8e
5 changed files with 235 additions and 166 deletions
Download patch file Download diff file Expand all files Collapse all files

164
README.rst
View file

@ -9,37 +9,6 @@ Pelican is a simple weblog generator, writen in python.
* Easy to interface with DVCSes and web hooks
* Completely static output, so easy to host anywhere !
Files metadata
--------------
Pelican tries to be smart enough to get the informations he 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.
You could provide the metadata in the restructured text files, using the
following syntax (give your file the `.rst` extension)::
My super title
##############
:date: 2010-10-03 10:20
:tags: thats, awesome
:category: yeah
:author: Alexis Metaireau
You can also use a markdown syntax (with a file ending in `.md`)::
Date: 2010-12-03
Title: My super title
Put you content here.
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`.
Features
--------
@ -52,142 +21,14 @@ Pelican currently supports:
* theming support (themes are done using `jinja2 <http://jinjna.pocoo.org>`_)
* PDF generation of the articles/pages (optional).
Getting started — Generate your blog
-------------------------------------
You're ready? Let's go ! You can install pelican in a lot of different ways,
the simpler one is via `pip <http://pip.openplans.org/>`_::
$ pip install pelican
Then, you have just to launch pelican, like this::
$ pelican /path/to/your/content/
And… that's all! You can see your weblog generated on 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).
You can create your own style if you want, have a look to the help to see all
the options you can use::
$ pelican --help
Pages
-----
If you create a folder named `pages`, all the files in it will be used to
generate static pages.
Settings
--------
Pelican is configurable thanks a configuration file, that you can pass to
the command line::
$ pelican -s path/to/your/settingsfile.py path
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 ?
======================= =======================================================
`SITEURL` base URL of your website.
`PATH` path to look at for input files.
`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)
`OUTPUT_PATH` Where to output the generated files. Default to
"output"
`SITENAME` Your site name,
`DISPLAY_PAGES_ON_MENU` Display or not the pages on the menu of the template.
Templates can follow or not this settings.
`PDF_PROCESSOR` Put True if you want to have PDF versions of your
documents. You will need to install `rst2pdf`.
`DEFAULT_CATEGORY` The default category to fallback on. `misc` by default.
`FALLBACK_ON_FS_DATE` If True, pelican will use the file system dates infos
(mtime) if it can't get informations from the
metadata?
`MARKUP` A list of available markup languages you want to use.
moment, only available values are `rst` and `md`.
`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.
`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)
`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')
======================= =======================================================
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
<http://alexis.notmyidea.org/pelican/themes.html>`_
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 ?
======================= =======================================================
`GITHUB_URL` Your github URL (if you have one), it will then
use it to create a github ribbon.
`DISQUS_SITENAME` Pelican can handle disqus comments, specify the
sitename you've filled in on disqus
`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.
`GOOGLE_ANALYTICS` 'UA-XXXX-YYYY' to activate google analytics.
======================= =======================================================
In addition, you can use the "wide" version of the `notmyidea` theme, by
adding that in your configuration::
CSS_FILE = "wide.css"
Have a look to `the documentation <http://alexis.notmyidea.org/pelican/>`_ for
more informations.
Why the name "Pelican" ?
------------------------
Heh, you didn't noticed? "Pelican" is an anagram for "Calepin" ;)
Dependencies
------------
At this time, pelican is dependent of the following python packages:
* feedgenerator, to generate the ATOM feeds.
* jinja2, for templating support.
* pygments, to have syntactic colorization
* docutils and Markdown
If you're not using python 2.7, you will also need `argparse`.
All those dependencies will be processed automatically if you install pelican
using setuptools/distribute or pip.
Source code
-----------
@ -197,7 +38,6 @@ or via git on http://github.com/ametaireau/pelican/
If you feel hackish, have a look to the `pelican's internals explanations
<http://alexis.notmyidea.org/pelican/internals.html>`_.
Feedback !
----------

6
docs/conf.py
View file

@ -21,14 +21,14 @@ pygments_style = 'sphinx'
# a list of builtin themes.
sys.path.append(os.path.abspath('_themes'))
html_theme_path = ['_themes']
html_theme = 'flask_small'
html_theme = 'flask'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
'index_logo': 'pelican.png',
'github_fork': 'ametaireau/pelican',
# 'index_logo': 'pelican.png',
# 'github_fork': 'ametaireau/pelican',
}
# Add any paths that contain custom themes here, relative to this directory.

87
docs/getting_started.rst Normal file
View file

@ -0,0 +1,87 @@
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 <http://pip.openplans.org/>`_::
$ 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::
$ virtualenv .
$ source bin/activate
$ python setup.py install
Dependencies
============
At this time, pelican is dependent of the following python packages:
* feedgenerator, to generate the ATOM feeds.
* jinja2, for templating support.
* pygments, to have syntactic colorization
* docutils and Markdown
If you're not using python 2.7, you will also need `argparse`.
All those dependencies will be processed automatically if you install pelican
using setuptools/distribute or pip.
Files metadata
==============
Pelican tries to be smart enough to get the informations he 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.
You could provide the metadata in the restructured text files, using the
following syntax (give your file the `.rst` extension)::
My super title
##############
:date: 2010-10-03 10:20
:tags: thats, awesome
:category: yeah
:author: Alexis Metaireau
You can also use a markdown syntax (with a file ending in `.md`)::
Date: 2010-12-03
Title: My super title
Put you content here.
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`.
Generate your blog
==================
To launch pelican, just use the `pelican` command::
$ pelican /path/to/your/content/
And… that's all! You can see your weblog generated on 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).
You can create your own style if you want, have a look to the help to see all
the options you can use::
$ pelican --help
Pages
=====
If you create a folder named `pages`, all the files in it will be used to
generate static pages.

1
docs/index.rst
View file

@ -1 +0,0 @@
../README.rst

53
docs/index.rst Normal file
View file

@ -0,0 +1,53 @@
Pelican
#######
Pelican is a simple weblog generator, writen 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.
* Easy to interface with DVCSes and web hooks
* Completely static output, so easy to host anywhere !
Documentation
=============
.. toctree::
:maxdepth: 2
getting_started
settings
themes
internals
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 <http://jinjna.pocoo.org>`_)
* PDF generation of the articles/pages (optional).
Why the name "Pelican" ?
========================
Heh, you didn't noticed? "Pelican" is an anagram for "Calepin" ;)
Source code
===========
You can access the source code via mercurial at http://hg.notmyidea.org/pelican/
or via git on http://github.com/ametaireau/pelican/
Feedback !
==========
If you want to see new features in Pelican, dont 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 !

90
docs/settings.rst Normal file
View file

@ -0,0 +1,90 @@
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
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 ?
======================= =======================================================
`SITEURL` base URL of your website.
`PATH` path to look at for input files.
`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)
`OUTPUT_PATH` Where to output the generated files. Default to
"output"
`SITENAME` Your site name,
`DISPLAY_PAGES_ON_MENU` Display or not the pages on the menu of the template.
Templates can follow or not this settings.
`PDF_PROCESSOR` Put True if you want to have PDF versions of your
documents. You will need to install `rst2pdf`.
`DEFAULT_CATEGORY` The default category to fallback on. `misc` by default.
`FALLBACK_ON_FS_DATE` If True, pelican will use the file system dates infos
(mtime) if it can't get informations from the
metadata?
`MARKUP` A list of available markup languages you want to use.
moment, only available values are `rst` and `md`.
`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.
`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)
`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')
======================= =======================================================
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
<http://alexis.notmyidea.org/pelican/themes.html>`_
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 ?
======================= =======================================================
`GITHUB_URL` Your github URL (if you have one), it will then
use it to create a github ribbon.
`DISQUS_SITENAME` Pelican can handle disqus comments, specify the
sitename you've filled in on disqus
`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.
`GOOGLE_ANALYTICS` 'UA-XXXX-YYYY' to activate google analytics.
======================= =======================================================
In addition, you can use the "wide" version of the `notmyidea` theme, by
adding that in your configuration::
CSS_FILE = "wide.css"