.. -*- restructuredtext -*-

HgBlog is a set of modifications to the Sphinx project to make it slightly more 
suitable as a blogging engine.  It's built for those of us who love using
reStructuredText markup to write documents.

The quickstart wizard handles setting up an HgBlog for you.  This includes all
of the usual things that the Sphinx quickstart utility does, but it creates a
Mercurial repository and installs a hook and intelligent ignores for you.  The
hook will automatically convert the ``.rst`` files that Mercurial is tracking
into HTML using Sphinx when you commit changes to the repository.

Additionally, when you pull changes in from a remote clone of the repository, 
the hook will do the conversion just like when you commit locally.  You can set
the hook up on remote clones as well.  The hook *only* converts ``.rst`` files
that are tracked by Mercurial.  This means you can work on new blog articles 
without committing them to the repository to have them not appear online.

Installation
============

There are several ways to install HgBlog:

* Using ``pip`` (recommended)::

    pip install -U hgblog

* Using ``easy_install``::

    easy_install hgblog

* From the CheeseShop

    * Download the ``.tar.gz`` file from `PyPI <http://2ze.us/m2M>`_
    * Extract the ``.tar.gz`` file
    * Run ``python setup.py install`` using the ``setup.py`` in the extracted directory

* Using Mercurial::

    hg qclone http://bitbucket.org/codekoala/hgblog
    cd hgblog
    hg qapply -a
    python setup.py install

Getting Started
===============

HgBlog leverages the existing quickstart wizard for Sphinx projects.  There 
are some modifications to reduce the number of steps required, so you should
be able to be up and running within a minute using::

    hgblog-quickstart

All you need to do is:

* Provide the directory on your filesystem that shall be used for your blogging
  needs.
* Provide a name for your blog
* Provide your name
* Select any extensions you may want to include in your blog

Once you do that, you should have a few new directories, one of which will be 
called ``source``.  This is where you should write your ``.rst`` articles.  When
you're done working on a particular article, you can use::

    hg add
    hg ci

...to add and commit it to your Mercurial repository.  At this point, Sphinx will
be asked to generate the HTML for your blog based on your ``.rst`` files.

TODOs
=====

* Implement Disqus commenting
* Add RSS feeds
* Include a simple, static HTML web server for faster results

