From 2d9563440e9b7c4b18e230237be6a2faa88978d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C4=93teris=20Caune?= Date: Fri, 28 Jul 2017 23:54:48 +0300 Subject: [PATCH] Cron syntax cheatsheet. Fixes #126 --- hc/front/urls.py | 1 + hc/front/views.py | 4 + static/css/docs_cron.css | 54 +++ templates/base.html | 1 + templates/front/base_docs.html | 3 + templates/front/cron_preview.html | 6 +- templates/front/docs_cron.html | 530 ++++++++++++++++++++++++++++++ 7 files changed, 598 insertions(+), 1 deletion(-) create mode 100644 static/css/docs_cron.css create mode 100644 templates/front/docs_cron.html diff --git a/hc/front/urls.py b/hc/front/urls.py index 23553286..5e3f5fbe 100644 --- a/hc/front/urls.py +++ b/hc/front/urls.py @@ -45,6 +45,7 @@ urlpatterns = [ url(r'^docs/$', views.docs, name="hc-docs"), url(r'^docs/api/$', views.docs_api, name="hc-docs-api"), + url(r'^docs/cron/$', views.docs_cron, name="hc-docs-cron"), url(r'^about/$', views.about, name="hc-about"), url(r'^privacy/$', views.privacy, name="hc-privacy"), url(r'^terms/$', views.terms, name="hc-terms"), diff --git a/hc/front/views.py b/hc/front/views.py index e212fa2b..81825015 100644 --- a/hc/front/views.py +++ b/hc/front/views.py @@ -139,6 +139,10 @@ def docs_api(request): return render(request, "front/docs_api.html", ctx) +def docs_cron(request): + ctx = {"page": "docs", "section": "cron"} + return render(request, "front/docs_cron.html", ctx) + def about(request): return render(request, "front/about.html", {"page": "about"}) diff --git a/static/css/docs_cron.css b/static/css/docs_cron.css new file mode 100644 index 00000000..b318da8e --- /dev/null +++ b/static/css/docs_cron.css @@ -0,0 +1,54 @@ + + +.cron-example th { + background: #f5f5f5; +} + +.cron-example th div { + padding: 5px; + margin: 5px; + font-family: monospace; + min-width: 28px; + text-align: center; +} + +.cron-example td { + position: relative; + padding: 8px; +} + +.cron-example .guide { + position: absolute; + top: 10px; + left: 50%; + bottom: 15px; + width: 40%; + + border-left: 2px dotted #ddd; + border-bottom: 2px dotted #ddd; +} + +.desc { + text-align: center; + font-weight: bold; + font-style: italic; + font-size: 20px; + color: #333; + padding: 8px; + margin-bottom: 8px; +} + +#cron-examples { + display: flex; + flex-direction: row; + flex-wrap: wrap; +} + +#cron-examples .panel { + width: 450px; + margin-right: 20px; +} + +.cron-example td.minor { + color: #999; +} \ No newline at end of file diff --git a/templates/base.html b/templates/base.html index cc0a2294..a4ee80f6 100644 --- a/templates/base.html +++ b/templates/base.html @@ -20,6 +20,7 @@ + diff --git a/templates/front/base_docs.html b/templates/front/base_docs.html index a57fee22..8490d46b 100644 --- a/templates/front/base_docs.html +++ b/templates/front/base_docs.html @@ -19,6 +19,9 @@
  • Email
    • +
  • + Cron Syntax +
  • REST API
    • diff --git a/templates/front/cron_preview.html b/templates/front/cron_preview.html index 27c98982..5abb2826 100644 --- a/templates/front/cron_preview.html +++ b/templates/front/cron_preview.html @@ -1,7 +1,11 @@ {% load humanize tz %} {% if bad_schedule %} -

    Invalid cron expression

    +

    + Invalid cron expression.
    + Please check the supported cron syntax features. + +

    {% elif bad_tz %}

    Invalid timezone

    {% else %} diff --git a/templates/front/docs_cron.html b/templates/front/docs_cron.html new file mode 100644 index 00000000..25f99957 --- /dev/null +++ b/templates/front/docs_cron.html @@ -0,0 +1,530 @@ +{% extends "front/base_docs.html" %} +{% load compress staticfiles hc_extras %} + +{% block title %}Cron Syntax Cheatsheet - {% site_name %}{% endblock %} + +{% block docs_content %} + +

    Cron Syntax Cheatsheet

    + +

    + {% site_name %} understands most of the traditional cron syntax features. + Under the hood, it uses the + croniter package + to parse and interpret cron expressions. Below is a showcase of + supported syntax features. +

    + +
    + +
    + +
    +
    +

    Basics

    +
    +
    +

    A cron expression has five fields, separated by spaces. + Asterisk is a wild card character and means "any value". +

    + +
    "Run every minute"
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    *
    *
    *
    *
    *
    +
    +     		+
    +     		+
    +     		+
    +     		+
    +     		Day of week, 0 - 7, 1=Monday
    + Month, 1 - 12 +
    + Day of month, 1 - 31 +
    + Hour of day, 0 - 23 +
    + Minute, 0 - 59 +
    +
    +
    + +
    +
    +

    Numeric values

    +
    +
    +

    Use numeric values instead of asterisks to match specific + minutes, hours, days and months. +

    + +
    "Run at 6PM on Fridays"
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    0
    18
    *
    *
    5
    +
    +     		+
    +     		+
    +     		+
    +     		+
    +     		Run only on Fridays
    + Run every month of the year +
    + Run every day of the month +
    + Run at 6PM +
    + Run at the start of the hour +
    +
    +
    + +
    +
    +

    Commas

    +
    +
    +

    Use {v1},{v2},...,{vn} to list multiple values.

    + +
    "Run at 9AM, 12PM and 6PM every day"
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    0
    9,12,18
    *
    *
    *
    +
    +     		+
    +     		+
    +     		+
    +     		+
    +     		Run on every weekday
    + Run every month of the year +
    + Run every day of the month +
    + Run at 9AM, 12PM and 6PM +
    + Run at the start of the hour +
    +
    +
    + +
    +
    +

    Ranges of values

    +
    +
    +

    Use {start}-{end} to define a range of matching values.

    + +
    "Run every minute on workdays"
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    *
    *
    *
    *
    1-5
    +
    +     		+
    +     		+
    +     		+
    +     		+
    +     		Run on Monday to Friday
    + Run every month of the year +
    + Run every day of the month +
    + Run every hour of the day +
    + Run every minute of the hour +
    +
    +
    + +
    +
    +

    Ranges with a step

    +
    +
    +

    Use {start}/{step} to define a range with a step.

    + +
    "Run every quarter of an hour"
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    0/15
    *
    *
    *
    *
    +
    +     		+
    +     		+
    +     		+
    +     		+
    +     		Run on every weekday
    + Run every month of the year +
    + Run every day of the month +
    + Run every hour of the day +
    + Run every 15 minutes, starting from minute 0 +
    +
    +
    + +
    +
    +

    Combine numeric values and ranges in lists

    +
    +
    +

    In the comma-separated lists you can combine not only + numeric values but also {start}-{end} and {start}/{step} + constructs.

    + +
    "Run every round hour outside office hours"
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    0
    18-23,0-8
    *
    *
    *
    +
    +     		+
    +     		+
    +     		+
    +     		+
    +     		Run on every weekday
    + Run every month of the year +
    + Run every day of the month +
    + Run at 6PM, 7PM, 8PM, ..., 7AM, 8AM +
    + Run at the start of the hour +
    +
    +
    + +
    +
    +

    Abbreviated day and month names

    +
    +
    +

    JAN-DEC can be used in the month field + and + MON-SUN in the weekday field. +

    + +
    "Run every round hour on April 1st"
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    0
    *
    1
    APR
    *
    +
    +     		+
    +     		+
    +     		+
    +     		+
    +     		Run on every weekday
    + Run in April +
    + Run on the first day of the month +
    + Run every hour of the day +
    + Run at the start of the hour +
    +
    +
    + +
    +
    +

    First, second, ... weekday

    +
    +
    +

    + Use {day-of-week}#{n} to define constructs + such as "first Saturday of the month". n is a + number from 1 to 5. +

    + +
    "Run at 2PM on the first Saturday +
    of every month"
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    0
    14
    *
    *
    6#1
    +
    +     		+
    +     		+
    +     		+
    +     		+
    +     		Run on the first saturday of the month
    + Run every month +
    + Run on any day of the month +
    + Run at 2PM +
    + Run at the start of the hour +
    +
    +
    + +
    +
    +

    Timezones

    +
    +
    +

    + Cron daemon uses server's local time. + If your server's timezone is other than UTC, make sure + to set a matching timezone for your check + on {% site_name %} as well. +

    + +

    On Ubuntu systems you can check the server's timezone + with:

    + 
    cat /etc/timezone
    +
    +
    + + + +
    + +{% endblock %}