From e0e62d8b8e93cf096c8c18dc66db221772e0d8a0 Mon Sep 17 00:00:00 2001 From: Alexis Metaireau Date: Tue, 14 Dec 2010 15:31:11 +0000 Subject: [PATCH] Update the documentation. --- README.rst | 164 +-------------------------------------- docs/conf.py | 6 +- docs/getting_started.rst | 87 +++++++++++++++++++++ docs/index.rst | 54 ++++++++++++- docs/settings.rst | 90 +++++++++++++++++++++ 5 files changed, 235 insertions(+), 166 deletions(-) create mode 100644 docs/getting_started.rst mode change 120000 => 100644 docs/index.rst create mode 100644 docs/settings.rst diff --git a/README.rst b/README.rst index 027f8198..71d94290 100644 --- a/README.rst +++ b/README.rst @@ -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 `_) * 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 `_:: - - $ 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 -`_ - -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 `_ 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 `_. - Feedback ! ---------- diff --git a/docs/conf.py b/docs/conf.py index 0efe92b2..159ddbcc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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. diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 00000000..df3b71d9 --- /dev/null +++ b/docs/getting_started.rst @@ -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 `_:: + + $ 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. + diff --git a/docs/index.rst b/docs/index.rst deleted file mode 120000 index 89a01069..00000000 --- a/docs/index.rst +++ /dev/null @@ -1 +0,0 @@ -../README.rst \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..9af7ff6b --- /dev/null +++ b/docs/index.rst @@ -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 `_) +* 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 ! + diff --git a/docs/settings.rst b/docs/settings.rst new file mode 100644 index 00000000..85679eb5 --- /dev/null +++ b/docs/settings.rst @@ -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 +`_ + +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"