ablog/README.rst

ABlog for Sphinx
================

ABlog is a Sphinx extension that converts any documentation or personal
website project into a full-fledged blog with:

  * `Atom feeds`_
  * `Archive pages`_
  * `Blog sidebars`_
  * `Disqus integration`_
  * `Font-Awesome integration`_

Looking for an example? Take a look at `ABlog documentation <http://ablog.readthedocs.org>`_ 
where each manual and release is a blog post ;) 

.. _Atom feeds: http://ablog.readthedocs.org/blog/atom.xml
.. _Archive pages: http://ablog.readthedocs.org/blog/
.. _Blog sidebars: http://ablog.readthedocs.org/manual/ablog-configuration-options/#sidebars
.. _Disqus integration: http://ablog.readthedocs.org/manual/ablog-configuration-options/#disqus-integration
.. _Font-Awesome integration: http://ablog.readthedocs.org/manual/ablog-configuration-options/#fa

Installation
------------

You can install ABlog using pip_::

    pip install -U ablog

This will install required packages Sphinx_ and Werkzeug_ as well, respectively for 
building your website and generating feeds.

If you don't already have a Sphinx project with a nice theme, you might want to 
install Alabaster_ too to start with a good looking website::

  pip install Alabaster

.. _pip: https://pip.pypa.io
.. _Sphinx: http://sphinx-doc.org/
.. _Werkzeug: http://werkzeug.pocoo.org/
.. _Alabaster: https://github.com/bitprophet/alabaster


Getting Started
---------------

If you are starting a new project, see `ABlog Quick Start`_ guide.

If you already have a project, enable blogging by editing ``conf.py`` as follows:

.. code-block:: python

  # 1. Append ablog to list of extensions
  extensions = [
      '...',
      'ablog'
  ]
  
  # 2a. Append ABlog templates path to `templates_path`
  import ablog
  templates_path.append(ablog.get_html_templates_path())

  # 2b. If `templates_path` is not defined before
  templates_path = [ablog.get_html_templates_path()]

If you have also installed Alabaster_, see here_ how to configure it.

.. _ABlog Quick Start: http://ablog.readthedocs.org/manual/ablog-quick-start
.. templates_path: http://sphinx-doc.org/config.html#confval-templates_path
.. here_: https://github.com/bitprophet/alabaster#installation

How it works
------------

You can convert *any page* to a post with the ``post`` directive as follows:

.. code-block:: rst

  .. post:: Apr 15, 2014
     :tags: python, earth, love, peace
     

ABlog will catalog all ``.rst`` files (pages) indicated as posts as above, 
whithout interfering with Sphinx's operations. Since any page from any folder 
in your project can be posted, you do not need to change how you organize
content in separate folders. 

When you are building HTML pages, posts will be included in archives and feeds 
specified by ``:tag:``, ``:category:``, etc. options automatically.

In additon, you can include a list of posts anywhere in your project 
simply using ``postlist`` directive:

.. code-block:: rst

  .. postlist:: 5
     :category: Manual
     :reverse:

For ABlog documentation, this converts to a list of links to the oldest 
five posts in Manual_ category:

  * `Posting and Listing <http://ablog.readthedocs.org/manual/posting-and-listing/>`_ 
  * `ABlog Configuration Options <http://ablog.readthedocs.org/manual/ablog-configuration-options/>`_ 
  * `Cross-referencing Blog Pages <http://ablog.readthedocs.org/manual/cross-referencing-blog-pages/>`_
  * `Post Excerpts and Images <http://ablog.readthedocs.org/manual/post-excerpts-and-images/>`_
  * `Posting Sections <http://ablog.readthedocs.org/manual/posting-and-listing/#posting-sections>`_
  

.. _Manual: http://ablog.readthedocs.org/blog/category/manual/