mirror of
https://github.com/vale981/ablog
synced 2025-03-05 09:11:38 -05:00
125 lines
3.6 KiB
ReStructuredText
125 lines
3.6 KiB
ReStructuredText
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.
|
|
|
|
|
|
.. _pip: https://pip.pypa.io
|
|
.. _Sphinx: http://sphinx-doc.org/
|
|
.. _Werkzeug: http://werkzeug.pocoo.org/
|
|
|
|
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.
|