1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
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:
*/*
|
