hiro/ablog
1
0
Fork 0
mirror of https://github.com/vale981/ablog synced 2025-03-06 01:31:39 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update README.rst

Browse source
This commit is contained in:
Ahmet Bakan 2015-03-01 09:35:16 -08:00
parent c3e25d14cc
commit fae1a5db26
1 changed files with 34 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

83
README.rst
View file

@ -30,96 +30,81 @@ You can install ABlog using pip_::
pip install -U ablog pip install -U ablog
In addition to Sphinx_, Werkzeug_ is required for generating feeds. This will also install required packages Sphinx_ and Werkzeug_, respectively required
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_ to start with a good looking website::
pip install Alabaster
.. _pip: https://pip.pypa.io .. _pip: https://pip.pypa.io
.. _Sphinx: http://sphinx-doc.org/ .. _Sphinx: http://sphinx-doc.org/
.. _Werkzeug: http://werkzeug.pocoo.org/ .. _Werkzeug: http://werkzeug.pocoo.org/
.. _Alabaster: https://github.com/bitprophet/alabaster
Getting Started Getting Started
--------------- ---------------
If you are starting a new project, see If you are starting a new project, see `ABlog Quick Start`_ guide.
`ABlog Quick Start <http://ablog.readthedocs.org/manual/ablog-quick-start>`_
guide.
To enable blogging in a Sphinx project, append ``ablog`` to the If you already have a project, enable blogging by editing ``conf.py``
list of extensions and ABlog template path to :confval:`templates_path` as follows:
in :file:`conf.py`:
.. code-block:: python .. code-block:: python
# 1. append ablog to list of extensions
extensions = [ extensions = [
'...', '...',
'ablog' 'ablog'
] ]
# 2a. append ABlog templates path to `templates_path`
import ablog import ablog
templates_path.append(ablog.get_html_templates_path()) templates_path.append(ablog.get_html_templates_path())
# if `templates_path` is not defined before # 2b. if `templates_path` is not defined before
templates_path = [ablog.get_html_templates_path()] templates_path = [ablog.get_html_templates_path()]
If you have also installed Alabaster_, see here_ how to configure it.
See more detailed instructions in :ref:`ablog-configuration-options` .. here_: https://github.com/bitprophet/alabaster#installation
and :ref:`posting-and-listing` posts.
**Read The Docs**
On `Read The Docs`_, ABlog may cause an exception when Sphinx build environment .. _ABlog Quick Start: http://ablog.readthedocs.org/manual/ablog-quick-start
is being pickled. To circumvent this problem, include the following .. templates_path: http://sphinx-doc.org/config.html#confval-templates_path
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 How it works
------------ ------------
ABlog catalogs all :file:`.rst` files indicated as posts and creates You can convert *any page* to a post with the ``post`` directive as follows:
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 .. code-block:: rst
.. post:: Apr 15, 2014 .. post:: Apr 15, 2014
:tags: python, earth, love, peace :tags: python, earth, love, peace
ABlog will include the page in specified archive pages and the blog feed. Here Goes Your Post or Page Title
=================================
You can include a list of posts anywhere simply using :rst:dir:`postlist` Followed by an awesome content!
ABlog catalogs all ``.rst`` files indicated as posts as above and creates
archive pages and blog feeds. It does not interfere with Sphinx's operations,
and you do not need to change how you structure content in separate folders.
ABlog will include the page in specified archive pages and the blog feed.
You can include a list of posts anywhere simply using ``postlist``
directive: directive:
.. code-block:: rst .. code-block:: rst
.. postlist:: 2 .. postlist:: 5
:category: Release :category: Manual
This converts to a list of links to the most recent five posts in This converts to a list of links to the most recent five posts in
:ref:`category-release` category: Manual_ category:
.. postlist:: 2 .. _Manual: http://ablog.readthedocs.org/blog/category/manual/
: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.