~nprescott/quiescent

ca41ac4f6df709fd533fd4e6ff6d1f27c0dc3552 — Nolan Prescott 2 years ago 27dfc36
Convert README, add CI config

  pandoc -f rst -t markdown -o README.md
7 files changed, 162 insertions(+), 144 deletions(-)

A .builds/debian.yml
A .builds/freebsd.yml
M MANIFEST.in
A README.md
D README.rst
M quiescent/bootstrap.py
M setup.py
A .builds/debian.yml => .builds/debian.yml +17 -0
@@ 0,0 1,17 @@
image: debian/stretch
packages:
  - python3-venv
  - python3-setuptools
sources:
  - https://git.sr.ht/~nprescott/quiescent
tasks:
  - setup: |
      cd quiescent
      python3 -m venv venv
      source venv/bin/activate
      pip install --upgrade pip
      pip install -e .
  - build: |
      cd quiescent
      source venv/bin/activate
      python setup.py test

A .builds/freebsd.yml => .builds/freebsd.yml +16 -0
@@ 0,0 1,16 @@
image: freebsd
packages:
  - python36
sources:
  - https://git.sr.ht/~nprescott/quiescent
tasks:
  - setup: |
      cd quiescent
      python3.6 -m venv venv
      . venv/bin/activate
      pip install --upgrade pip
      pip install -e .
  - build: |
      cd quiescent
      . venv/bin/activate
      python setup.py test

M MANIFEST.in => MANIFEST.in +1 -1
@@ 1,1 1,1 @@
include README.rst COPYING
include README.md COPYING

A README.md => README.md +125 -0
@@ 0,0 1,125 @@
Quiescent
=========

*Simplified static site generation*

Quiescent is a static site generator focused on eliminating complexity
in creating weblog-like sites. It is built around the idea of static
assets and plain-text, utilizing a hierarchical directory and URL
structure for ease of use in hyperlinking and deploying to web-servers.
All *posts* are written in
[Markdown](https://daringfireball.net/projects/markdown/), and later
converted to plain HTML, there is support for publishing static assets
such as images or JavaScript.

Quiescent does very little magic and aims only to simplify the annoying
or boring parts of site creation, so that the focus remains on content.
As such, the only parts of the resulting site that are automatically
generated are the [Atom feed](https://tools.ietf.org/html/rfc4287), an
index page, and an *archive* of all posts.

Quiescent uses [Mistune](https://github.com/lepture/mistune) for
markdown parsing, and Python 3.

Installation
------------

    pip install quiescent

Usage
-----

The interface to the program is through the `quiescent` command, which
takes an optional argument `-c` or `--config`, to name a [configuration
.ini](https://docs.python.org/3/library/configparser.html) file other
than the default `config.ini`.

    cd blog-dir/
    quiescent --bootstrap  # initial configuration
    quiescent              # equivalent to quiescent --config config.ini

In order for the program to run as intended, the `config.ini` file must
be modified to suit the destination site.

The following templates are required and included in the `--bootstrap`
command upon initial configuration:

 -   archive.html
 -   index.html
 -   post.html

### Templates

Quiescent implements its own code-generating template engine. The intent
is for the majority of a template to be plain HTML, with a small number
of points for data (usually written post information) to be "injected".
The syntax is summarized below, more examples are available in the
sample templates provided by the `--bootstrap` command:

    {{variable_name}}

    {{object.attribute}}

    {% for item in iterable %}
    {{item}}
    {% endfor %}

    {% if some_test %}
    this text is conditional
    {% endif %}

### Tips for Writing

All posts written require a title and a date using a specific format at
the beginning of the markdown file. The format is as follows:

    title: <post title>
    date: <must match the date format in config.ini>
    +++

An important note to keep in mind when writing posts, the links used in
referencing local media (images, style sheets, etc.) are used directly
in the Atom feed, which may break relative URLs. A solution to this (and
the author's recommendation) is to specify a base URL and link relative
to that, so that links resolve correctly throughout the generated
content of the site.

### Publishing

Due to the design of `quiescent`, the contents and directory output from
the generation process is suitable for any basic web-server capable of
serving static files. In the case of the project author, after the site
is *built*, simply `rsync`-ing the entire *build* directory is
sufficient, for example:

    cd build
    rsync -avz . user@example.com:/static/file/directory

### Direction

Because of the wide variety of static site generators available this
project has a specific focus, with no plans to implement the following:

> -   a local web-server
> -   multiple input formats
> -   comments
> -   cross-post-to-twitter
> -   tags

### Development, Testing

The project contains some unittests which are runnable using the
`setup.py` command and require no additional dependencies or
configuration.

    $ python setup.py -q test
    ....................................
    ----------------------------------------------------------------------
    Ran 36 tests in 0.012s

    OK

License
-------

GPLv3, see COPYING for more information

D README.rst => README.rst +0 -140
@@ 1,140 0,0 @@
Quiescent
=========

*Simplified static site generation*

Quiescent is a static site generator focused on eliminating complexity in
creating weblog-like sites. It is built around the idea of static assets and
plain-text, utilizing a hierarchical directory and URL structure for ease of
use in hyperlinking and deploying to web-servers. All *posts* are written in
`Markdown <https://daringfireball.net/projects/markdown/>`_, and later converted
to plain HTML, there is support for publishing static assets such as images or
JavaScript.

Quiescent does very little magic and aims only to simplify the annoying or
boring parts of site creation, so that the focus remains on content. As such,
the only parts of the resulting site that are automatically generated are the
`Atom feed <https://tools.ietf.org/html/rfc4287>`_, an index page, and an
*archive* of all posts.

Quiescent uses `Mistune <https://github.com/lepture/mistune>`_ for markdown
parsing, and Python 3.6.

Installation
------------

::

   pip install quiescent

Usage
-----

The interface to the program is through the ``quiescent`` command, which takes
an optional argument ``-c`` or ``--config``, to name a `configuration .ini
<https://docs.python.org/3/library/configparser.html>`_ file other than the
default ``config.ini``.

::

   cd blog-dir/
   quiescent --bootstrap  # initial configuration
   quiescent              # equivalent to quiescent --config config.ini

In order for the program to run as intended, the ``config.ini`` file must be
modified to suit the destination site.

The following templates are required and included in the
``--bootstrap`` command upon initial configuration:

 - archive.html
 - index.html
 - post.html

Templates
~~~~~~~~~

Quiescent implements its own code-generating template engine. The
intent is for the majority of a template to be plain HTML, with a
small number of points for data (usually written post information) to
be "injected". The syntax is summarized below, more examples are
available in the sample templates provided by the ``--bootstrap``
command:

::

   {{variable_name}}
   
   {{object.attribute}}

   {% for item in iterable %}
   {{item}}
   {% endfor %}

   {% if some_test %}
   this text is conditional
   {% endif %}
   

Tips for Writing
~~~~~~~~~~~~~~~~

All posts written require a title and a date using a specific format at the
beginning of the markdown file. The format is as follows:

::

   title: <post title>
   date: <must match the date format in config.ini>
   +++

An important note to keep in mind when writing posts, the links used in
referencing local media (images, style sheets, etc.) are used directly in the
Atom feed, which may break relative URLs. A solution to this (and the author's
recommendation) is to specify a base URL and link relative to that, so that
links resolve correctly throughout the generated content of the site.

Publishing
~~~~~~~~~~

Due to the design of ``quiescent``, the contents and directory output from the
generation process is suitable for any basic web-server capable of serving
static files. In the case of the project author, after the site is *built*,
simply ``rsync``-ing the entire *build* directory is sufficient, for example:

::

   cd build
   rsync -avz . user@example.com:/static/file/directory


Direction
~~~~~~~~~

Because of the wide variety of static site generators available this project
has a specific focus, with no plans to implement the following:

  - a local web-server
  - multiple input formats
  - comments
  - cross-post-to-twitter
  - tags

Development, Testing
~~~~~~~~~~~~~~~~~~~~

The project contains some unittests which are runnable using the ``setup.py``
command and require no additional dependencies or configuration.

::

   $ python setup.py -q test
   ....................................
   ----------------------------------------------------------------------
   Ran 36 tests in 0.012s

   OK

License
-------
GPLv3, see COPYING for more information

M quiescent/bootstrap.py => quiescent/bootstrap.py +2 -2
@@ 88,7 88,7 @@ feed link = feed.atom
            os.makedirs(directory)
        except Exception:
            logger.warning('{directory} directory already exists'
                           .format(directory=directory)
                           .format(directory=directory))

    for each_file, template in (config, index, archive, post):
        try:


@@ 96,4 96,4 @@ feed link = feed.atom
                f.write(template)
        except FileExistsError:
            logger.warning('{each_file} already exists'
                           .format(each_file=each_file)
                           .format(each_file=each_file))

M setup.py => setup.py +1 -1
@@ 1,7 1,7 @@
from setuptools import setup

def readme():
    with open('README.rst') as f:
    with open('README.md') as f:
        return f.read()

setup(name="quiescent",