mirror of
https://github.com/vale981/ablog
synced 2025-03-05 09:11:38 -05:00
Synced index and readme, removed py 3.3 from travis builds.
This commit is contained in:
Ahmet Bakan
parent
19af16ae60
commit
7716e2af2e
4 changed files with 89 additions and 83 deletions
|
|
@ -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:
|
||||
|
|
|
|||
35
README.rst
35
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 <http://ablog.readthedocs.org>`_
|
||||
where each manual and release is a blog post ;)
|
||||
Looking for an example? Take a look at `ABlog documentation <http://ablog.readthedocs.org>`_
|
||||
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 <http://sphinx-doc.org/>`_ 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 <http://ablog.readthedocs.org/manual/posting-and-listing/>`_
|
||||
* `ABlog Configuration Options <http://ablog.readthedocs.org/manual/ablog-configuration-options/>`_
|
||||
* `Posting and Listing <http://ablog.readthedocs.org/manual/posting-and-listing/>`_
|
||||
* `ABlog Configuration Options <http://ablog.readthedocs.org/manual/ablog-configuration-options/>`_
|
||||
* `Cross-referencing Blog Pages <http://ablog.readthedocs.org/manual/cross-referencing-blog-pages/>`_
|
||||
* `Post Excerpts and Images <http://ablog.readthedocs.org/manual/post-excerpts-and-images/>`_
|
||||
* `Posting Sections <http://ablog.readthedocs.org/manual/posting-and-listing/#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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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/
|
||||
|
|
|
|||
132
docs/index.rst
132
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 <http://ablog.readthedocs.org/blog/atom.xml>`_
|
||||
* `Archives <http://ablog.readthedocs.org/manual/cross-referencing-blog-pages/#archives>`_
|
||||
* `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>`_
|
||||
* `Atom feeds`_
|
||||
* `Archive pages`_
|
||||
* `Blog sidebars`_
|
||||
* `Disqus integration`_
|
||||
* `Font-Awesome integration`_
|
||||
|
||||
Looking for an example? Take a look at `ABlog documentation <http://ablog.readthedocs.org>`_ ;)
|
||||
Looking for an example? Take a look at `ABlog documentation <http://ablog.readthedocs.org>`_
|
||||
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 <http://sphinx-doc.org/>`_ 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 <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 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 <http://ablog.readthedocs.org/manual/posting-and-listing/>`_
|
||||
* `ABlog Configuration Options <http://ablog.readthedocs.org/manual/ablog-configuration-options/>`_
|
||||
* `Cross-referencing Blog Pages <http://ablog.readthedocs.org/manual/cross-referencing-blog-pages/>`_
|
||||
* `Post Excerpts and Images <http://ablog.readthedocs.org/manual/post-excerpts-and-images/>`_
|
||||
* `Posting Sections <http://ablog.readthedocs.org/manual/posting-and-listing/#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.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue