
################
django-bigmouth
################

``django-bigmouth`` provides a `Django`_ interface to the `Pelican`_ static blog
generator.

Introduction
============

What?
-----

A Django app that provides a management command (``run_pelican``) that acts as
a thin facade over the `Pelican`_ blog generation process, together with various
templatetags to assist with custom template creation, and the ability to preview
the blog via the development server and Django flatpages.

Why?
----

You might use ``bigmouth`` rather than `Pelican`_ itself if you have an existing
dynamic Django app to which you want to add a static blog while making use of
your app's templating and static file setup, or if you simply prefer Django
templates to Jinja templates.



Quickstart - running the example project
========================================

It is assumed that everything that is required to run Python and Django is
installed on your system. We also assume a unix/BSD system, but a windows
setup shouldn't be too dissimilar to what follows.

Source
------

First get the source, for example::

    pip download bigmouth

or the latest version::

    git clone ssh://git@github.com/devopsni/django-bigmouth.git

Buildout
--------

In the root directory of the files just downloaded, run the ``bootstrap.py`` file::

    python bootstrap.py

This should create, among other things, a local ``bin`` directory. Now you should
run the ``bin/buildout`` script, but if you are familiar with buildout you
might want to look at the buildout.cfg file and update as required. The
``eggs-directory`` settings is set to ``../eggs``, ie. a sibling rather than a
child of the current directory.

So now run::

    ./bin/buildout

and this should initialize a local sandboxed environment. In particular,
``bigmouth`` depends on the latest `Pelican`_ and this will have been cloned
from github to the ``develop-src`` directory.

If all went well, running::

    ./bin/django

should print a list of available management commands and these should include
a command called ``run_pelican``.

Database
--------

Before you can create the example blog, you have to create a database and
configure the Django settings file appropriately. This is the standard Django
database setup step for which the Django docs provide all the info you need.
It's the DATABASES parameter in the ``bigmouth_example/settings.py`` which need
to be changed to match the database you create.

If you are using postgresql you could look at the included ``pgreset`` script.
This is a utlity shell script which will create a postgresql database and user.
For example::

    pushd bigmouth_example/etc/postgres
    ./pgreset
    popd

or, depending on your postgresql configuration::

    sudo -u postgres ./pgreset

On completion, ``pgreset`` will print the required DATABASES setting which you
can then copy and paste to the settings file.

Once the database is created and configured, run the ``syncdb`` management command::

    ./bin/django syncdb

Note, that a database isn't strictly required if you pass ``--no-flatpages`` as
a parameter to the ``run_pelican`` command (and you are not interested in previewing
the files via the development server), but a database is recommended and could well
become a requirement at some point.


mkblog
------

Now you are ready to create the example blog application and the easiest way is
to run the ``mkblog`` utility which simply wraps the call to the ``run_pelican``
command::

    ./mkblog

and then view the blog by running::

    ./bin/django runserver

and visiting http://127.0.0.1:8000/ .


.. _Pelican: http://readthedocs.org/docs/pelican/en/latest/
.. _Django: https://www.djangoproject.com/


