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

It's a Blog... It's a Documentation... It's Sphinx with ABlog

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

  * `Atom feeds`_, e.g. `ABlog feed`_
  * `Archive pages`_, e.g. `ABlog archive`_
  * `Blog sidebars`_ with including tag cloud, archive links, etc.
  * `Disqus integration`_
  * `Font-Awesome integration`_

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

.. _Atom feeds: http://ablog.readthedocs.org/manual/ablog-configuration-options/#blog-feeds
.. _ABlog feed: http://ablog.readthedocs.org/blog/atom.xml
.. _Archive pages: http://ablog.readthedocs.org/manual/cross-referencing-blog-pages/#archives
.. _ABlog archive: 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

In addition to Sphinx_, Werkzeug_ is required for generating feeds.


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

If you are starting a new project, see
`ABlog Quick Start <http://ablog.readthedocs.org/manual/ablog-quick-start>`_
guide.

To enable blogging in a Sphinx project, append ``ablog`` to the
list of extensions and ABlog template path to :confval:`templates_path`
in :file:`conf.py`:

.. code-block:: python

  extensions = [
      '...',
      'ablog'
  ]
  import ablog
  templates_path.append(ablog.get_html_templates_path())

  # if `templates_path` is not defined before
  templates_path = [ablog.get_html_templates_path()]


See more detailed instructions in :ref:`ablog-configuration-options`
and :ref:`posting-and-listing` posts.

**Read The Docs**

On `Read The Docs`_, ABlog may cause an exception when Sphinx build environment
is being pickled.  To circumvent this problem, include the following
in :file:`conf.py`::

  if os.environ.get('READTHEDOCS', None) == 'True':
      skip_pickling = True

This should not effect how the documentation is built.

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

ABlog catalogs all :file:`.rst` files indicated as posts and creates
archive pages and a blog feed. It does not interfere with Sphinx's operations,
and you do not need to change how you structure content in separate folders.

You can convert *any page*, containing a new usage example or a new release
announcement, to a post with the :rst:dir:`post` directive as follows:

.. code-block:: rst

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

ABlog will include the page in specified archive pages and the blog feed.

You can include a list of posts anywhere simply using :rst:dir:`postlist`
directive:

.. code-block:: rst

  .. postlist:: 2
     :category: Release

This converts to a list of links to the most recent five posts in
:ref:`category-release` category:

.. postlist:: 2
   :category: Release


Learn More
----------

You can learn more about ablog features in the following posts:

.. postlist:: 10
   :category: Manual
   :sort:


Feedback
--------

ABlog has been used with the Sphinx_ 1.2.2, Python 2.7 and 3.4
to generate its documentation blog. If you try it with different
Python and Sphinx versions, please give feedback to help us improve it.