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

Edited README.

Browse source
This commit is contained in:
Ahmet Bakan 2015-02-25 23:24:19 -08:00
parent 4b213e6c49
commit 77bfb3538d
2 changed files with 107 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

99
README.rst
View file

@ -12,4 +12,101 @@ website project into a full-fledged blog with:
* `Disqus integration <http://ablog.readthedocs.org/manual/ablog-configuration-options/#disqus-integration>`_
* `Font-Awesome integration <http://ablog.readthedocs.org/manual/ablog-configuration-options/#fa>`_
Looking for an example? See `ABlog documentation <http://ablog.readthedocs.org>`_ ;)
Looking for an example? Take a look at `ABlog documentation <http://ablog.readthedocs.org>`_ ;)
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.

14
docs/index.rst
View file

@ -12,7 +12,7 @@ website project into a full-fledged blog with:
* `Disqus integration <http://ablog.readthedocs.org/manual/ablog-configuration-options/#disqus-integration>`_
* `Font-Awesome integration <http://ablog.readthedocs.org/manual/ablog-configuration-options/#fa>`_
Looking for an example? Just browse `ABlog documentation <http://ablog.readthedocs.org>`_ ;)
Looking for an example? Take a look at `ABlog documentation <http://ablog.readthedocs.org>`_ ;)
Installation
------------
@ -24,8 +24,12 @@ You can install ABlog using pip_::
In addition to Sphinx_, Werkzeug_ is required for generating feeds.
Configuration
-------------
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`
@ -90,8 +94,8 @@ This converts to a list of links to the most recent five posts in
:category: Release
Documentation
-------------
Learn More
----------
You can learn more about ablog features in the following posts: