From 7716e2af2e9de117e5f9c2989ffda29463884177 Mon Sep 17 00:00:00 2001 From: Ahmet Bakan Date: Sun, 1 Mar 2015 14:06:51 -0800 Subject: [PATCH] Synced index and readme, removed py 3.3 from travis builds. --- .travis.yml | 3 +- README.rst | 35 +++++++------ docs/conf.py | 2 - docs/index.rst | 132 ++++++++++++++++++++++++++----------------------- 4 files changed, 89 insertions(+), 83 deletions(-) diff --git a/.travis.yml b/.travis.yml index 3a88073..8f9c273 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,10 +1,9 @@ language: python python: - 2.7 - - 3.3 - 3.4 before_install: - - pip install alabaster + - pip install Sphinx Werkzeug alabaster install: - pip install . script: diff --git a/README.rst b/README.rst index 7bfc6a5..a1ad3d8 100644 --- a/README.rst +++ b/README.rst @@ -7,7 +7,7 @@ .. image:: https://pypip.in/d/ABlog/badge.png :target: https://crate.io/packages/ablog - + ABlog for Sphinx ================ @@ -20,8 +20,8 @@ website project into a full-fledged blog with: * `Disqus integration`_ * `Font-Awesome integration`_ -Looking for an example? Take a look at `ABlog documentation `_ -where each manual and release is a blog post ;) +Looking for an example? Take a look at `ABlog documentation `_ +where each manual and release is a blog post ;) .. _Atom feeds: http://ablog.readthedocs.org/blog/atom.xml .. _Archive pages: http://ablog.readthedocs.org/blog/ @@ -36,16 +36,15 @@ You can install ABlog using pip_:: pip install -U ablog -This will install Sphinx_ and Werkzeug_ as well, respectively required for -building your website and generating feeds. +This will install `Sphinx `_ and Werkzeug_ as well, +respectively required for building your website and generating feeds. -If you are starting a new Sphinx project, you might want to also install +If you are starting a new Sphinx project, you might want to also install Alabaster_ to have 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 @@ -64,7 +63,7 @@ If you already have a project, enable blogging by making following changes in `` '...', 'ablog' ] - + # 2a. Append templates path to `templates_path` import ablog templates_path.append(ablog.get_html_templates_path()) @@ -80,9 +79,9 @@ If you also installed Alabaster_, see how to configure it here_. How it works ------------ -If you are new to Sphinx_ and reStructuredText markup language, +If you are new to Sphinx_ and reStructuredText markup language, you might find `reStructuredText Primer`_ useful. Once you have -some content (in ``.rst`` files), you can post *any page* using +some content (in ``.rst`` files), you can post *any page* using the ``post`` directive as follows: .. code-block:: rst @@ -92,11 +91,11 @@ the ``post`` directive as follows: :category: python :author: me :location: SF - :language: en + :language: en ABlog will index all files posted as above. When building HTML pages, -it will create archives and feeds that list these posts as -specified by ``:tag:``, ``:category:``, etc. options. +it will create archives and feeds that list these posts as +specified by ``:tag:``, ``:category:``, etc. options. You can also include a list of posts using ``postlist`` directive: @@ -109,16 +108,16 @@ You can also include a list of posts using ``postlist`` directive: For ABlog documentation, this converts to the following list of links that you can follow to learn more about configuring and using ABlog: - * `Posting and Listing `_ - * `ABlog Configuration Options `_ + * `Posting and Listing `_ + * `ABlog Configuration Options `_ * `Cross-referencing Blog Pages `_ * `Post Excerpts and Images `_ * `Posting Sections `_ - + .. _reStructuredText Primer: http://sphinx-doc.org/rest.html -For existing projects, it is important to note that ABlog does not intertere +For existing projects, it is important to note that ABlog does not intertere with any Sphinx operations. Since you can post any page from any folder, -you do not need to change how you organize project contents. +you do not need to change how you organize project contents. diff --git a/docs/conf.py b/docs/conf.py index 8ccdd5f..a7abb45 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -110,9 +110,7 @@ extlinks = { rst_epilog = ''' .. _Sphinx: http://sphinx-doc.org/ .. _Python: http://python.org -.. _pip: http://www.pip-installer.org/ .. _Disqus: http://disqus.com/ -.. _Werkzeug: http://werkzeug.pocoo.org/ .. _GitHub: https://github.com/abakan/ablog .. _PyPI: https://pypi.python.org/pypi/ablog .. _Read The Docs: https://readthedocs.org/ diff --git a/docs/index.rst b/docs/index.rst index f69ddf1..a1ad3d8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,18 +1,33 @@ +.. image:: https://secure.travis-ci.org/abakan/ablog.png?branch=devel + :target: http://travis-ci.org/#!/abakan/ablog + +.. image:: https://pypip.in/v/ABlog/badge.png + :target: https://pypi.python.org/pypi/ABlog + +.. image:: https://pypip.in/d/ABlog/badge.png + :target: https://crate.io/packages/ablog + + ABlog for Sphinx ================ -It's a Blog... It's a Documentation... It's Sphinx with ABlog - -ABlog is a Sphinx extension that can convert any documentation or personal +ABlog is a Sphinx extension that converts any documentation or personal website project into a full-fledged blog with: - * `Atom feeds `_ - * `Archives `_ - * `Sidebars `_ - * `Disqus integration `_ - * `Font-Awesome integration `_ + * `Atom feeds`_ + * `Archive pages`_ + * `Blog sidebars`_ + * `Disqus integration`_ + * `Font-Awesome integration`_ -Looking for an example? Take a look at `ABlog documentation `_ ;) +Looking for an example? Take a look at `ABlog documentation `_ +where each manual and release is a blog post ;) + +.. _Atom feeds: http://ablog.readthedocs.org/blog/atom.xml +.. _Archive pages: 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 ------------ @@ -21,93 +36,88 @@ You can install ABlog using pip_:: pip install -U ablog -In addition to Sphinx_, Werkzeug_ is required for generating feeds. +This will install `Sphinx `_ and Werkzeug_ as well, +respectively required for building your website and generating feeds. + +If you are starting a new Sphinx project, you might want to also install +Alabaster_ to have a good looking website:: + + pip install Alabaster + +.. _pip: https://pip.pypa.io +.. _Werkzeug: http://werkzeug.pocoo.org/ +.. _Alabaster: https://github.com/bitprophet/alabaster Getting Started --------------- -If you are starting a new project, see -`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 making following changes in ``conf.py``: .. code-block:: python + # 1. Append 'ablog' to list of extensions extensions = [ '...', 'ablog' ] + + # 2a. Append 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 also installed Alabaster_, see how to configure it here_. -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. +.. _ABlog Quick Start: http://ablog.readthedocs.org/manual/ablog-quick-start +.. _here: https://github.com/bitprophet/alabaster#installation 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: +If you are new to Sphinx_ and reStructuredText markup language, +you might find `reStructuredText Primer`_ useful. Once you have +some content (in ``.rst`` files), you can post *any page* using +the ``post`` directive as follows: .. code-block:: rst .. post:: Apr 15, 2014 - :tags: python, earth, love, peace + :tags: earth, love, peace + :category: python + :author: me + :location: SF + :language: en -ABlog will include the page in specified archive pages and the blog feed. +ABlog will index all files posted as above. When building HTML pages, +it will create archives and feeds that list these posts as +specified by ``:tag:``, ``:category:``, etc. options. -You can include a list of posts anywhere simply using :rst:dir:`postlist` -directive: +You can also include a list of posts using ``postlist`` directive: .. code-block:: rst - .. postlist:: 2 - :category: Release + .. postlist:: 5 + :category: Manual + :reverse: -This converts to a list of links to the most recent five posts in -:ref:`category-release` category: +For ABlog documentation, this converts to the following list of links that you +can follow to learn more about configuring and using ABlog: -.. postlist:: 2 - :category: Release + * `Posting and Listing `_ + * `ABlog Configuration Options `_ + * `Cross-referencing Blog Pages `_ + * `Post Excerpts and Images `_ + * `Posting Sections `_ -Learn More ----------- +.. _reStructuredText Primer: http://sphinx-doc.org/rest.html -You can learn more about ablog features in the following posts: +For existing projects, it is important to note that ABlog does not intertere +with any Sphinx operations. Since you can post any page from any folder, +you do not need to change how you organize project contents. -.. 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.