{ "info": { "author": "Roman Dobosz", "author_email": "gryf73@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Environment :: Console", "Intended Audience :: End Users/Desktop", "License :: OSI Approved :: BSD License", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Topic :: Internet :: WWW/HTTP", "Topic :: Text Processing :: Linguistic", "Topic :: Text Processing :: Markup", "Topic :: Text Processing :: Markup :: HTML" ], "description": "What is Kiroku?\n---------------\n\nKiroku is a tool written in Python for creating and build a fully static blog or\nweb page. That means, no server side language, framework,\n*mod_python*/*mod_wsgi* is needed. To serve such generated content pure web\nserver is more than enough.\n\nSome highlights:\n\n* Almost no external dependencies (only `docutils`_ is required)\n* Works with Python 3\n* Modifiable templates\n* Simple search\n* Generated RSS channel\n* i18n aware\n* Configurable via ``ini`` file\n\nKiroku (\u559c\u516d, in the meaning of putting something into the record; writing\nsomething) name was chosen for this project before I realized, that there\nalready are software projects with the same name. Most of them are inactive, so\nI decided to keep that name.\n\nRequirements\n------------\n\nBesides (obviously) Python 3, there is only one dependency - `docutils`_.\n\nFor proper date time representation, `pytz`_ module is highly recommended,\nunless you are lucky to live in the ``Europe/Warsaw`` or ``UTC`` time zones, or\nyou simply don't care, and stick with local time represented in UTC format.\n\nLast possible dependency is `pygments`_, which *automagically* enables syntax\nhighlight in code blocks.\n\nInstallation\n------------\n\n#. Install globally\n\n .. code:: shell-session\n\n root@localhost # pip install kiroku\n\n#. Virtualenv is one option\n\n .. code:: shell-session\n\n user@localhost $ virtualenv-python3.2 blog\n New python executable in py3/bin/python3.2\n Also creating executable in py3/bin/python\n Installing distribute...done.\n Installing pip...done.\n user@localhost $ cd blog\n user@localhost blog $ . bin/activate\n (blog)user@localhost blog $ pip install kiroku\n\n#. Also, it can be download and used directly:\n\n .. code:: shell-session\n\n user@localhost $ git clone https://bitbucket.org/gryf/kiroku.git\n user@localhost $ cd kiroku\n user@localhost kiroku $ PYTHONPATH=/home/user/kiroku python3 scripts/kiroku --help\n\n Note, that ``PYTHONPATH`` should be defined correctly.\n\nUsage\n-----\n\nOnce installed, ``kiroku`` command should be available, and can be used for\nbuilding the structure of the blog or web side:\n\n .. code:: shell-session\n\n user@localhost $ kiroku init blog\n\nThis command will create default directory structure, under which several items\nwill be available:\n\n- ``articles`` - directory where all articles/posts shall be stored\n- ``.css`` - contents of this directory will be copied into destination\n ``build`` - directory as ``css``. All modification to the CSS should be done\n there. File ``/.css/style.css`` is the default (and only) CSS file. Note, that\n during build every file with extension ``.css`` will be minified.\n- ``.js`` - directory with JavaScript files. Will be copied to ``build/js``\n during build.\n- ``.templates`` - this directory contains all the templates that Kiroku uses\n to build the pages.\n\nNow, just change the directory to ``blog`` and issue the command ``build`` to\ngenerate entire site:\n\n .. code:: shell-session\n\n user@localhost $ cd blog\n user@localhost blog $ kiroku build\n\nGenerated HTML files, style, JavaScript files - all of that will be placed in\nthe ``build`` directory.\n\nArticles/pages\n--------------\n\nEvery article, which should be taken into considerations should be placed in\n``articles`` directory. Images should be placed in a subdirectory (``images``,\n``img``, ``graphics``, ``res`` are the common choices). Files can be named in\nany convention, but in two conditions: they must have ``.rst`` extension, and\nthey have to be on the root of the ``articles`` directory. Kiroku will not scan\nthat directory recursively. Articles can have date prefix, just to have them\nchronologically sorted, for example ``2001-12-17_foo.rst``.\n\nThere is one special article file which is treated differently - ``about.rst``.\nIt doesn't have any fields mentioned below; they will not be processed. As the\nname suggest, this is *About me* page.\n\nEach page is a simple reST document. There are two modifications, that are\nimplemented in the kiroku module, which *make difference* from ordinary reST\ndocument:\n\n#. ``More`` comment.\n\n If the author place the comment ``.. more`` in the article, it will inform\n the Kiroku, where to cut the page and place the first part (a summary of the\n article, perhaps) of it on the index page, archive, description fields on RSS\n and so on. Example:\n\n .. code:: rest\n\n Hendrerit sem, eu tempor nisi felis et metus. Etiam gravida sem ut mi.\n\n .. more\n\n Vivamus lacus libero, aliquam eget, iaculis quis, tristique adipiscing,\n diam. Vivamus nec massa non justo iaculis pellentesque. Aenean accumsan\n elit sit amet nibh feugiat semper.\n\n That will make only first line to appear on the front page.\n\n Placing it on the page is not mandatory, so there is no point to\n do it on short articles, but it is a good idea to put it on the huge\n articles, since several huge articles on the front page can annoy readers.\n\n This idea was taken from blogger platform, but I think, that I saw that on\n other blog platforms too.\n\n#. Special fields\n\n `Fields`_ are special elements, which may (or may not) be present on the\n document itself, but their role is rather to describe reST document, then\n make significant appearance on that document itself.\n\n Kiroku use three fields, which will be utilized to describe an article:\n\n - ``:Title:`` - Field should contain the title of the article. If leaved\n empty, it will be guessed from the file name.\n - ``:Datetime:`` - Creation date. If not provided it will inherit the value\n from article file creation time. Format, as described on `datetime module`_\n is as follows:\n\n .. code:: python\n\n \"%Y-%m-%d %H:%M:%S\"\n # for example:\n \"2000-01-24 17:33:31\"\n\n - ``:Tags:`` - Comma separated labels for the article. Of course, can be\n unset.\n\n All of those fields are optional but it's highly recommended to have them on\n the articles. All fields can be lowrcase or upercase - it does not matter.\n\nArticle example:\n\n.. code:: rest\n\n :Title: My article\n :datetime: 2000-01-24 17:33:31\n :TAGS: Lorem ipsum, blog, cats\n\n A subsection\n ------------\n\n Phasellus eu quam. Quisque interdum cursus purus. In orci. Maecenas vehicula.\n Sed et mauris. Praesent feugiat viverra lacus. Suspendisse pulvinar lacus ut\n nunc. Quisque nisi. Suspendisse id risus nec nisi ultrices ornare. Donec eget\n tellus. Nullam molestie placerat felis. Aenean facilisis. Nunc erat.\n\n .. more\n\n Another subsection\n ------------------\n\n Luctus et ultrices posuere cubilia Curae; Morbi urna dui, fermentum quis,\n feugiat imperdiet, imperdiet id, sapien. Phasellus auctor nunc. Vivamus eget\n augue quis neque vestibulum placerat. Duis placerat. Maecenas accumsan rutrum\n lacus. Vestibulum lacinia semper nibh. Aenean diam odio, scelerisque at,\n ullamcorper nec, tincidunt dapibus, quam. Duis vel ante nec tortor porta\n mollis. Praesent orci. Cras dignissim vulputate metus.\n\nIf `pygments`_ module is present in the system, syntax highlighting for the code\nblocks can be enabled. It is enough to put the appropriate language for such\nblock, for example::\n\n .. code:: python\n\n print(\"hi\")\n\nIt will produce:\n\n .. code:: python\n\n print(\"hi\")\n\nConfiguration\n-------------\n\nKiroku provides simple configuration via ``config.ini`` file. After the\ninitialization there is an example for the configuration in the file\n``config.ini.example``. It can be renamed to the ``config.ini`` and then edited.\n\nFollowing options under ``[kiroku]`` section are available:\n\n- ``locale`` (default ``C``) - language of the web pages.\n- ``server_name`` (default ``localhost``) - target server name. It'll be used\n for links in RSS and for `favicon`.\n- ``server_root`` (default ``/``) - The root of the page/blog can be set here.\n If set to ``foo``, all the full links will be prefixed with it, i.e.\n ``http://localhost/foo/link.html``.\n- ``server_protocol`` (default ``http``) - It may be changed to ``https``\n- ``site_name`` (default ``Kiroku``) - Site name. It will be displayed at the\n top of the page.\n- ``site_desc`` (default ``Yet another blog``) - description of the\n website/blog. By default only seen on the RSS description tag.\n- ``site_footer`` (default ``The footer``) - footer of the page.\n- ``timezone`` (default ``UTC``) - proper name of the time zone the dates should\n be represent. Without `pytz`_ module, there is only ``Europe/Warsaw`` and\n ``UTC`` time zones implemented.\n\nBesides configuration, there is possibility to influence the look of the page by\nsimply adjusting the CSS file and the templates, which can be found under\n``.css`` and ``.templates`` directories respectively.\n\nTranslations\n------------\n\nFor now only Polish translation is available. Any help with translation is\nwelcomed :)\n\nDevelopment\n-----------\n\nFor development, `virtualenv`_ is strongly recommended. Following dependencies\nand tools are required. Python packages:\n\n- `coverage`_ - tool for code coverage measurement\n- `slimit`_ - for minifying JavaScript files\n\nAlthough not necessary, but recommended are two additional packages:\n\n- `pep8`_\n- `pylint`_\n\nWhich **should** be used during development.\n\nAll Python dependencies can be installed inside *virtualenv* environment with\n``pip`` command:\n\n.. code:: shell-session\n\n user@localhost $ virtualenv -p python3 kiroku-ve\n user@localhost $ cd kiroku-ve\n user@localhost kiroku-ve $ . bin/activate\n (kiroku-ve)user@localhost kiroku-ve $ pip install -r dev-requirements.txt\n\nAmong the mentioned above packages it will also (try to) install `docutils`_ and\n`pygments`_ modules.\n\nIf there is a plan for creating new message catalogs, or generating them, there\nwill be also `GNU gettext`_ needed (tools like ``xgettext`` and ``msgfmt`` in\nparticular).\n\nUsually, for simple tasks automation I've been using ``Makefile`` and ``make``\nutility, or the `paver`_ python task manager. However I've been trying to\ndecrease external dependencies only to the really necessary modules, so I've\nimplemented extra commands to the setup script, so that it can do a bit more\nthan you'll expect from ``setup.py`` :)\n\nThe commands are as follows:\n\n- ``test`` - execute the tests, and display the code coverage for them,\n- ``minify`` - minify JavaScript files (for now it is only one),\n- ``genpot`` - generate ``.pot`` file out of the source files. File\n ``kiroku.pot`` will be placed under ``kiroku/data/locale`` directory,\n- ``gencat`` - generate message catalogs for every available source ``.po``\n files.\n\nNote, that during build, message catalogs will (try to) be regenerated,\notherwise the interface will be in English by default, regardless of the\nlanguage in the config.\n\n``test`` command may have two additional parameters:\n\n- ``--verbose`` or ``-v`` - will turn on all of the messages printed out by the\n modules. This could be useful for debugging with ``pdb``.\n- ``--coverage`` or ``-c`` - will measure and print out the code coverage\n\nEvery command should be executed in the root directory of the Kiroku repository\n(the directory where ``setup.py`` exists).\n\nTODO\n----\n\nThere is still much to do. Here is the list of things I'm planning to do:\n\n#. Module ``kiroku.naive_tzinfo`` should be expanded to support more timezones.\n\n Timezones are needed because of the ``pubDate`` tag in RSS and ``datetime``\n attribute in ``