Update README.rst

README.rst

@@ -30,96 +30,81 @@ You can install ABlog using pip_::
 
     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
 .. _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 <http://ablog.readthedocs.org/manual/ablog-quick-start>`_
-guide.
+If you are starting a new project, see `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`:
+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())
 
-  # if `templates_path` is not defined before
+  # 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.
 
-See more detailed instructions in :ref:`ablog-configuration-options`
-and :ref:`posting-and-listing` posts.
+.. here_: https://github.com/bitprophet/alabaster#installation
 
-**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.
+.. _ABlog Quick Start: http://ablog.readthedocs.org/manual/ablog-quick-start
+.. templates_path: http://sphinx-doc.org/config.html#confval-templates_path
 
 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:
+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
+     
+  Here Goes Your Post or Page Title
+  =================================
+  
+  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 :rst:dir:`postlist`
+You can include a list of posts anywhere simply using ``postlist``
 directive:
 
 .. code-block:: rst
 
-  .. postlist:: 2
-     :category: Release
+  .. postlist:: 5
+     :category: Manual
 
 This converts to a list of links to the most recent five posts in
-:ref:`category-release` category:
+Manual_ category:
 
-.. postlist:: 2
-   :category: Release
+.. _Manual: http://ablog.readthedocs.org/blog/category/manual/
 
-
-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.