Package: kiroku
What is Kiroku?Kiroku is a tool written in Python for creating and build a fully static blog or
web page. That means, no server side language, framework,mod_python/mod_wsgiis needed. To serve such generated content pure web
server is more than enough.Some highlights:Almost no external dependencies (onlydocutilsis required)Works with Python 3Modifiable templatesSimple searchGenerated RSS channeli18n awareConfigurable viainifileKiroku (喜六, in the meaning of putting something into the record; writing
something) name was chosen for this project before I realized, that there
already are software projects with the same name. Most of them are inactive, so
I decided to keep that name.RequirementsBesides (obviously) Python 3, there is only one dependency -docutils.For proper date time representation,pytzmodule is highly recommended,
unless you are lucky to live in theEurope/WarsaworUTCtime zones, or
you simply don’t care, and stick with local time represented in UTC format.Last possible dependency ispygments, whichautomagicallyenables syntax
highlight in code blocks.InstallationInstall globallyroot@localhost #pipinstallkirokuVirtualenv is one optionuser@localhost $virtualenv-python3.2blogNew python executable in py3/bin/python3.2
Also creating executable in py3/bin/python
Installing distribute...done.
Installing pip...done.user@localhost $cdbloguser@localhost blog $.bin/activate(blog)user@localhost blog $pipinstallkirokuAlso, it can be download and used directly:user@localhost $gitclonehttps://bitbucket.org/gryf/kiroku.gituser@localhost $cdkirokuuser@localhost kiroku $PYTHONPATH=/home/user/kirokupython3scripts/kiroku--helpNote, thatPYTHONPATHshould be defined correctly.UsageOnce installed,kirokucommand should be available, and can be used for
building the structure of the blog or web side:user@localhost $kirokuinitblogThis command will create default directory structure, under which several items
will be available:articles- directory where all articles/posts shall be stored.css- contents of this directory will be copied into destinationbuild- directory ascss. All modification to the CSS should be done
there. File/.css/style.cssis the default (and only) CSS file. Note, that
during build every file with extension.csswill be minified..js- directory with JavaScript files. Will be copied tobuild/jsduring build..templates- this directory contains all the templates that Kiroku uses
to build the pages.Now, just change the directory toblogand issue the commandbuildto
generate entire site:user@localhost $cdbloguser@localhost blog $kirokubuildGenerated HTML files, style, JavaScript files - all of that will be placed in
thebuilddirectory.Articles/pagesEvery article, which should be taken into considerations should be placed inarticlesdirectory. Images should be placed in a subdirectory (images,img,graphics,resare the common choices). Files can be named in
any convention, but in two conditions: they must have.rstextension, and
they have to be on the root of thearticlesdirectory. Kiroku will not scan
that directory recursively. Articles can have date prefix, just to have them
chronologically sorted, for example2001-12-17_foo.rst.There is one special article file which is treated differently -about.rst.
It doesn’t have any fields mentioned below; they will not be processed. As the
name suggest, this isAbout mepage.Each page is a simple reST document. There are two modifications, that are
implemented in the kiroku module, whichmake differencefrom ordinary reST
document:Morecomment.If the author place the comment.. morein the article, it will inform
the Kiroku, where to cut the page and place the first part (a summary of the
article, perhaps) of it on the index page, archive, description fields on RSS
and so on. Example:Hendrerit sem, eu tempor nisi felis et metus. Etiam gravida sem ut mi... moreVivamus lacus libero, aliquam eget, iaculis quis, tristique adipiscing,diam.  Vivamus nec massa non justo iaculis pellentesque. Aenean accumsanelit sit amet nibh feugiat semper.That will make only first line to appear on the front page.Placing it on the page is not mandatory, so there is no point to
do it on short articles, but it is a good idea to put it on the huge
articles, since several huge articles on the front page can annoy readers.This idea was taken from blogger platform, but I think, that I saw that on
other blog platforms too.Special fieldsFieldsare special elements, which may (or may not) be present on the
document itself, but their role is rather to describe reST document, then
make significant appearance on that document itself.Kiroku use three fields, which will be utilized to describe an article::Title:- Field should contain the title of the article. If leaved
empty, it will be guessed from the file name.:Datetime:- Creation date. If not provided it will inherit the value
from article file creation time. Format, as described ondatetime moduleis as follows:"%Y-%m-%d%H:%M:%S"# for example:"2000-01-24 17:33:31":Tags:- Comma separated labels for the article. Of course, can be
unset.All of those fields are optional but it’s highly recommended to have them on
the articles. All fields can be lowrcase or upercase - it does not matter.Article example::Title:My article:datetime:2000-01-24 17:33:31:TAGS:Lorem ipsum, blog, catsA subsection------------Phasellus eu quam. Quisque interdum cursus purus. In orci. Maecenas vehicula.Sed et mauris. Praesent feugiat viverra lacus. Suspendisse pulvinar lacus utnunc. Quisque nisi. Suspendisse id risus nec nisi ultrices ornare. Donec egettellus. Nullam molestie placerat felis. Aenean facilisis. Nunc erat... moreAnother subsection------------------Luctus et ultrices posuere cubilia Curae; Morbi urna dui, fermentum quis,feugiat imperdiet, imperdiet id, sapien. Phasellus auctor nunc. Vivamus egetaugue quis neque vestibulum placerat. Duis placerat. Maecenas accumsan rutrumlacus. Vestibulum lacinia semper nibh. Aenean diam odio, scelerisque at,ullamcorper nec, tincidunt dapibus, quam. Duis vel ante nec tortor portamollis. Praesent orci. Cras dignissim vulputate metus.Ifpygmentsmodule is present in the system, syntax highlighting for the code
blocks can be enabled. It is enough to put the appropriate language for such
block, for example:.. code:: python

   print("hi")It will produce:print("hi")ConfigurationKiroku provides simple configuration viaconfig.inifile. After the
initialization there is an example for the configuration in the fileconfig.ini.example. It can be renamed to theconfig.iniand then edited.Following options under[kiroku]section are available:locale(defaultC) - language of the web pages.server_name(defaultlocalhost) - target server name. It’ll be used
for links in RSS and forfavicon.server_root(default/) - The root of the page/blog can be set here.
If set tofoo, all the full links will be prefixed with it, i.e.http://localhost/foo/link.html.server_protocol(defaulthttp) - It may be changed tohttpssite_name(defaultKiroku) - Site name. It will be displayed at the
top of the page.site_desc(defaultYet another blog) - description of the
website/blog. By default only seen on the RSS description tag.site_footer(defaultThe footer) - footer of the page.timezone(defaultUTC) - proper name of the time zone the dates should
be represent. Withoutpytzmodule, there is onlyEurope/WarsawandUTCtime zones implemented.Besides configuration, there is possibility to influence the look of the page by
simply adjusting the CSS file and the templates, which can be found under.cssand.templatesdirectories respectively.TranslationsFor now only Polish translation is available. Any help with translation is
welcomed :)DevelopmentFor development,virtualenvis strongly recommended. Following dependencies
and tools are required. Python packages:coverage- tool for code coverage measurementslimit- for minifying JavaScript filesAlthough not necessary, but recommended are two additional packages:pep8pylintWhichshouldbe used during development.All Python dependencies can be installed insidevirtualenvenvironment withpipcommand:user@localhost $virtualenv-ppython3kiroku-veuser@localhost $cdkiroku-veuser@localhost kiroku-ve $.bin/activate(kiroku-ve)user@localhost kiroku-ve $pipinstall-rdev-requirements.txtAmong the mentioned above packages it will also (try to) installdocutilsandpygmentsmodules.If there is a plan for creating new message catalogs, or generating them, there
will be alsoGNU gettextneeded (tools likexgettextandmsgfmtin
particular).Usually, for simple tasks automation I’ve been usingMakefileandmakeutility, or thepaverpython task manager. However I’ve been trying to
decrease external dependencies only to the really necessary modules, so I’ve
implemented extra commands to the setup script, so that it can do a bit more
than you’ll expect fromsetup.py:)The commands are as follows:test- execute the tests, and display the code coverage for them,minify- minify JavaScript files (for now it is only one),genpot- generate.potfile out of the source files. Filekiroku.potwill be placed underkiroku/data/localedirectory,gencat- generate message catalogs for every available source.pofiles.Note, that during build, message catalogs will (try to) be regenerated,
otherwise the interface will be in English by default, regardless of the
language in the config.testcommand may have two additional parameters:--verboseor-v- will turn on all of the messages printed out by the
modules. This could be useful for debugging withpdb.--coverageor-c- will measure and print out the code coverageEvery command should be executed in the root directory of the Kiroku repository
(the directory wheresetup.pyexists).TODOThere is still much to do. Here is the list of things I’m planning to do:Modulekiroku.naive_tzinfoshould be expanded to support more timezones.Timezones are needed because of thepubDatetag in RSS anddatetimeattribute in<time>HTML5 tags. To decrease dependencies I’ve decided to
implement anaïveimplementation for timezone info object and for nowonlyfor CET/CEST timezone. The goal is to make itpytzcompatible, so
Kiroku can use it if available. Done.Module for comments.I’m not decided yet on the way to append comments system (if any). For sure
an obvious choice could be adapting the templates to utilizedisqusor
similar commenting system, use some self-hosted solution (likeisso), or
even go with moderated (through the email) solutions, as described inMatt
Palmer blogpost.Make the templates use some engine likejinjaormako. Initially, I
have plan to do that, but eventually I’ve decided to keep Kiroku simple.
Maybe, if the interest will be big enough, I’ll add it later.LicenseThis software is licensed under Simplified BSD License:Copyright (c) 2013, Roman Dobosz
 All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

 1. Redistributions of source code must retain the above copyright notice, this
    list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright notice,
    this list of conditions and the following disclaimer in the documentation
    and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.