mirror of
https://github.com/vale981/ablog
synced 2025-03-04 08:41:40 -05:00
112 lines
3.5 KiB
ReStructuredText
112 lines
3.5 KiB
ReStructuredText
ABlog for Sphinx
|
|
================
|
|
|
|
.. image:: https://travis-ci.org/sunpy/ablog.svg?branch=master
|
|
:target: https://travis-ci.org/sunpy/ablog
|
|
.. image:: https://circleci.com/gh/sunpy/ablog.svg?style=svg
|
|
:target: https://circleci.com/gh/sunpy/ablog
|
|
.. image:: https://ci.appveyor.com/api/projects/status/cmmiadqoy5lx7l78?svg=true
|
|
:target: https://ci.appveyor.com/project/sunpy/ablog
|
|
|
|
|
|
Note
|
|
----
|
|
|
|
Please note that is an official new home of `Ahmet Bakan's Ablog Sphinx extension <https://github.com/abakan/ablog/>`__.
|
|
This version is maintined with the aim to keep it working for SunPy's website and thus new features are unlikely.
|
|
|
|
ABlog
|
|
-----
|
|
|
|
ABlog is a Sphinx extension that converts any documentation or personal website project into a full-fledged blog with:
|
|
|
|
* `Atom feeds`_
|
|
* `Archive pages`_
|
|
* `Blog sidebars`_
|
|
* `Disqus integration`_
|
|
* `Font-Awesome integration`_
|
|
* `Easy GitHub Pages deploys`_
|
|
* `Jupiter Notebook Support for blog posts`_
|
|
|
|
.. _Atom feeds: https://ablog.readthedocs.org/blog/atom.xml
|
|
.. _Archive pages: https://ablog.readthedocs.org/blog/
|
|
.. _Blog sidebars: https://ablog.readthedocs.org/manual/ablog-configuration-options/#sidebars
|
|
.. _Disqus integration: https://ablog.readthedocs.org/manual/ablog-configuration-options/#disqus-integration
|
|
.. _Font-Awesome integration: https://ablog.readthedocs.org/manual/ablog-configuration-options/#fa
|
|
.. _Easy GitHub Pages deploys: https://ablog.readthedocs.org/manual/deploy-to-github-pages/
|
|
.. _Jupiter Notebook Support for blog posts: https://ablog.readthedocs.org/manual/notebook_support/
|
|
|
|
Installation
|
|
------------
|
|
|
|
You can install ABlog using pip_::
|
|
|
|
pip install -U ablog
|
|
|
|
or anaconda_::
|
|
|
|
conda config --add channels conda-forge
|
|
conda install ablog
|
|
|
|
This will also install `Sphinx <http://sphinx-doc.org/>`__, Alabaster_, Werkzeug_, and Invoke_ respectively required for building your website, making it look good, generating feeds, and running deploy commands.
|
|
|
|
.. _pip: https://pip.pypa.io
|
|
.. _anaconda: https://www.anaconda.com/
|
|
.. _Werkzeug: https://werkzeug.pocoo.org/
|
|
.. _Alabaster: https://github.com/bitprophet/alabaster
|
|
.. _Invoke: https://www.pyinvoke.org/
|
|
|
|
Getting Started
|
|
---------------
|
|
|
|
If you are starting a new project, see `ABlog Quick Start`_ guide.
|
|
|
|
If you already have a project, enable blogging by making following changes in ``conf.py``:
|
|
|
|
.. code-block:: python
|
|
|
|
# 1. Add 'ablog' to list of extensions
|
|
extensions = [
|
|
'...',
|
|
'ablog'
|
|
]
|
|
|
|
# 2. Add ablog templates path
|
|
import ablog
|
|
|
|
# 2a. if `templates_path` is not defined
|
|
templates_path = [ablog.get_html_templates_path()]
|
|
|
|
# 2b. if `templates_path` is defined
|
|
templates_path.append(ablog.get_html_templates_path())
|
|
|
|
.. _ABlog Quick Start: https://ablog.readthedocs.org/manual/ablog-quick-start
|
|
|
|
How it works
|
|
------------
|
|
|
|
If you are new to Sphinx and reStructuredText markup language, you might find `reStructuredText Primer`_ useful.
|
|
Once you have content (in ``.rst`` files), you can post *any page* using the ``post`` directive as follows:
|
|
|
|
.. code-block:: rst
|
|
|
|
.. post:: Apr 15, 2014
|
|
:tags: earth, love, peace
|
|
:category: python
|
|
:author: me
|
|
:location: SF
|
|
:language: en
|
|
|
|
ABlog will index all files posted as above and list them in archives and feeds specified in ``:tag:``, ``:category:``, etc. options.
|
|
|
|
You can also include a list of posts using ``postlist`` directive:
|
|
|
|
.. code-block:: rst
|
|
|
|
.. postlist::
|
|
:list-style: circle
|
|
:category: Manual
|
|
:format: {title}
|
|
:sort:
|
|
|
|
.. _reStructuredText Primer: http://sphinx-doc.org/rest.html
|