115 lines
3.9 KiB
ReStructuredText
115 lines
3.9 KiB
ReStructuredText
|
:title: Data Sources
|
|||
|
|
:date: 2022-09-22
|
|||
|
|
|
|||
|
|
============
|
|||
|
|
Data Sources
|
|||
|
|
============
|
|||
|
|
|
|||
|
|
The diagram below shows the data sources and variables that can be used in
|
|||
|
|
templates.
|
|||
|
|
|
|||
|
|
::
|
|||
|
|
|
|||
|
|
┌─────────────────┐
|
|||
|
|
│ settings.toml ├───► site, pygments_theme ──┐
|
|||
|
|
└─────────────────┘ │
|
|||
|
|
│
|
|||
|
|
┌─────────────────┐ ┌────────▼────────┐
|
|||
|
|
│ *.rst ├───► page, html ───► template.jinja2 │
|
|||
|
|
└────────┬────────┘ └────────▲────────┘
|
|||
|
|
│ │
|
|||
|
|
┌────────▼────────┐ │
|
|||
|
|
│ Aggregated data ├───► aggr ──────────────────┘
|
|||
|
|
└─────────────────┘
|
|||
|
|
|
|||
|
|
\*.rst Files
|
|||
|
|
============
|
|||
|
|
|
|||
|
|
The \*.rst files contain a part with document attributes called Docinfo (see
|
|||
|
|
`field lists`_ and `bibliographic elements`_) and a part with the content of
|
|||
|
|
the article.
|
|||
|
|
|
|||
|
|
You can come up with your own attributes. Attributes can contain only strings.
|
|||
|
|
|
|||
|
|
There some special attributes used by rSW:
|
|||
|
|
|
|||
|
|
============ =============== =========================
|
|||
|
|
Attribute Required Deafult
|
|||
|
|
============ =============== =========================
|
|||
|
|
``type`` No page
|
|||
|
|
``template`` No template.jinja2
|
|||
|
|
``date`` Yes None
|
|||
|
|
``title`` No None
|
|||
|
|
============ =============== =========================
|
|||
|
|
|
|||
|
|
type
|
|||
|
|
Article type. Can be post for blog posts or ``page`` for standalone
|
|||
|
|
pages.
|
|||
|
|
|
|||
|
|
template
|
|||
|
|
The template to be used when rendering the HTML page.
|
|||
|
|
|
|||
|
|
The attribute value must be the path to the template file relative to the
|
|||
|
|
template directory. For example, the templates/index.jinja2 file would be:
|
|||
|
|
|
|||
|
|
.. code-block:: rst
|
|||
|
|
|
|||
|
|
:template: index.jinja2
|
|||
|
|
|
|||
|
|
The path to the templates directory and default template can be overridden
|
|||
|
|
in **settings.toml**.
|
|||
|
|
|
|||
|
|
date
|
|||
|
|
Date in ISO format YYYY-MM-DD. This attribute is used to sort the list of
|
|||
|
|
posts. The date format can be overridden in **settings.toml**.
|
|||
|
|
|
|||
|
|
title
|
|||
|
|
Title of the article. It is not required and is not processed by rSW in
|
|||
|
|
any way, but it is desirable to fill it for use in templates.
|
|||
|
|
|
|||
|
|
.. note::
|
|||
|
|
|
|||
|
|
The ``authors`` attribute is `special`_ and is not yet supported by rSW.
|
|||
|
|
Using ``authors`` will result in an error when building the site.
|
|||
|
|
|
|||
|
|
settings.toml
|
|||
|
|
=============
|
|||
|
|
|
|||
|
|
The configuration file has a special ``site`` section, all data from which is
|
|||
|
|
passed to the template unchanged.
|
|||
|
|
|
|||
|
|
The structure and data types can be arbitrary. The file uses the
|
|||
|
|
`TOML <https://toml.io/>`_ format.
|
|||
|
|
|
|||
|
|
For example, in this way you can pass basic information about the site:
|
|||
|
|
|
|||
|
|
.. code-block:: toml
|
|||
|
|
|
|||
|
|
[site]
|
|||
|
|
title = 'My site'
|
|||
|
|
name = 'My awesome site'
|
|||
|
|
description = 'Awesome site about awesome things'
|
|||
|
|
datetime_format = '%d %b %Y'
|
|||
|
|
|
|||
|
|
A special variable ``pygments_theme`` is also passed to the template from the
|
|||
|
|
configuration file. It contains the value of ``pygments.theme``.
|
|||
|
|
|
|||
|
|
Aggregated data
|
|||
|
|
===============
|
|||
|
|
|
|||
|
|
A dictionary with aggregated data. This data is collected during site
|
|||
|
|
generation before HTML-pages are rendered.
|
|||
|
|
|
|||
|
|
Aggregated data contains lists of blog posts and standalone pages.
|
|||
|
|
|
|||
|
|
The list of posts is sorted in descending order by date from the ``date``
|
|||
|
|
attribute.
|
|||
|
|
|
|||
|
|
The next article will describe the use of this data in templates.
|
|||
|
|
|
|||
|
|
.. Links
|
|||
|
|
|
|||
|
|
.. _field lists: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html\#field-lists
|
|||
|
|
.. _bibliographic elements: https://docutils.sourceforge.io/docs/ref/doctree.html#bibliographic-elements
|
|||
|
|
.. _special: https://docutils.sourceforge.io/docs/ref/doctree.html#authors
|