105 lines
2.6 KiB
ReStructuredText
105 lines
2.6 KiB
ReStructuredText
|
ABlog for Sphinx
|
||
|
|
================
|
||
|
|
|
||
|
|
ABlog is a Sphinx extension that converts any documentation or personal website project into a full-fledged blog with:
|
||
|
|
|
||
|
|
* :ref:`Atom feeds <blog-feed>`
|
||
|
|
* :ref:`Archive pages <blog-archives>`
|
||
|
|
* :ref:`sidebars`
|
||
|
|
* :ref:`disqus-integration`
|
||
|
|
* :ref:`Font-Awesome integration <font-awesome>`
|
||
|
|
* :doc:`manual/markdown`
|
||
|
|
|
||
|
|
Ablog is part of the `SunPy Project <https://www.sunpy.org>`__.
|
||
|
|
|
||
|
|
.. _installation:
|
||
|
|
|
||
|
|
Installation
|
||
|
|
------------
|
||
|
|
|
||
|
|
You can install ABlog using `pip <https://pip.pypa.io/en/stable/>`__::
|
||
|
|
|
||
|
|
pip install -U ablog
|
||
|
|
|
||
|
|
or `miniforge <https://github.com/conda-forge/miniforge>`__::
|
||
|
|
|
||
|
|
conda install ablog
|
||
|
|
|
||
|
|
This will also install `Sphinx <http://sphinx-doc.org/>`__, `feedgen <https://github.com/lkiesow/python-feedgen>`__, and `Invoke <https://www.pyinvoke.org/>`__ respectively required for building your website, making it look good, generating feeds, and running deploy commands.
|
||
|
|
|
||
|
|
Getting Started
|
||
|
|
---------------
|
||
|
|
|
||
|
|
If you are starting a new project, see the :ref:`quick-start` guide.
|
||
|
|
If you already have a project, enable blogging by making following changes in ``conf.py``:
|
||
|
|
|
||
|
|
.. code-block:: python
|
||
|
|
|
||
|
|
# 1. Add 'ablog' and 'sphinx.ext.intersphinx' to the list of extensions
|
||
|
|
extensions = [
|
||
|
|
'...',
|
||
|
|
'ablog',
|
||
|
|
'sphinx.ext.intersphinx',
|
||
|
|
]
|
||
|
|
|
||
|
|
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 :rst:dir:`post` directive as follows:
|
||
|
|
|
||
|
|
.. _reStructuredText Primer: https://www.sphinx-doc.org/en/master/
|
||
|
|
|
||
|
|
.. code-block:: rst
|
||
|
|
|
||
|
|
.. post:: Apr 15, 2014
|
||
|
|
:tags: earth, love, peace
|
||
|
|
:category: python
|
||
|
|
:author: me
|
||
|
|
:location: SF
|
||
|
|
:language: en
|
||
|
|
|
||
|
|
An alternative method is:
|
||
|
|
|
||
|
|
.. code-block:: rst
|
||
|
|
|
||
|
|
:blogpost: true
|
||
|
|
:date: Oct 10, 2020
|
||
|
|
:author: Nabil Freij
|
||
|
|
:location: World
|
||
|
|
:category: Manual
|
||
|
|
:language: English
|
||
|
|
|
||
|
|
at the top of the file.
|
||
|
|
|
||
|
|
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 :rst:dir:`postlist` directive:
|
||
|
|
|
||
|
|
.. code-block:: rst
|
||
|
|
|
||
|
|
.. postlist::
|
||
|
|
:list-style: circle
|
||
|
|
:category: Manual
|
||
|
|
:format: {title}
|
||
|
|
:sort:
|
||
|
|
|
||
|
|
For ABlog documentation, this converts to the following where you can find more about configuring and using ABlog:
|
||
|
|
|
||
|
|
.. postlist::
|
||
|
|
:category: Manual
|
||
|
|
:list-style: circle
|
||
|
|
:format: {title}
|
||
|
|
:sort:
|
||
|
|
|
||
|
|
.. only:: html
|
||
|
|
|
||
|
|
.. image:: https://readthedocs.org/projects/ablog/badge/?version=latest
|
||
|
|
:target: https://ablog.readthedocs.io
|
||
|
|
|
||
|
|
.. toctree::
|
||
|
|
:hidden:
|
||
|
|
:glob:
|
||
|
|
|
||
|
|
*/*
|