Syntax highlighting for API examples.

hc/front/management/commands/pygmentize.py

@@ -1,13 +1,15 @@
 from django.core.management.base import BaseCommand
 
 
-def _process(fin, fout, lexer):
+def _process(name, lexer):
     from pygments import highlight
     from pygments.formatters import HtmlFormatter
-    source = open("templates/front/snippets/" + fin).read()
+    source = open("templates/front/snippets/%s.txt" % name).read()
     processed = highlight(source, lexer, HtmlFormatter())
     processed = processed.replace("PING_URL", "{{ ping_url }}")
-    with open("templates/front/snippets/" + fout, "w") as out:
+    processed = processed.replace("SITE_ROOT", "{{ SITE_ROOT }}")
+    processed = processed.replace("PING_ENDPOINT", "{{ PING_ENDPOINT }}")
+    with open("templates/front/snippets/%s.html" % name, "w") as out:
         out.write(processed)
 
 
@@ -24,11 +26,17 @@ class Command(BaseCommand):
             self.stdout.write("  pip install Pygments\n\n")
             return
 
-        _process("bash.txt", "bash.html", lexers.BashLexer())
-        _process("browser.txt", "browser.html", lexers.JavascriptLexer())
-        _process("crontab.txt", "crontab.html", lexers.BashLexer())
-        _process("python.txt", "python.html", lexers.PythonLexer())
-        _process("php.txt", "php.html", lexers.PhpLexer())
-        _process("powershell.txt", "powershell.html",
-                 lexers.shell.PowerShellLexer())
-        _process("node.txt", "node.html", lexers.JavascriptLexer())
+        # Invocation examples
+        _process("bash", lexers.BashLexer())
+        _process("browser", lexers.JavascriptLexer())
+        _process("crontab", lexers.BashLexer())
+        _process("python", lexers.PythonLexer())
+        _process("php", lexers.PhpLexer())
+        _process("powershell", lexers.shell.PowerShellLexer())
+        _process("node", lexers.JavascriptLexer())
+
+        # API examples
+        _process("list_checks_request", lexers.BashLexer())
+        _process("list_checks_response", lexers.JsonLexer())
+        _process("create_check_request", lexers.BashLexer())
+        _process("create_check_response", lexers.JsonLexer())

templates/front/docs_api.html

@@ -8,7 +8,7 @@
 <h2>REST API</h2>
 <p>
 This is early days for healtchecks.io REST API. For now, there's just
-one API resource for listing/creating checks.
+one API resource for listing and creating checks.
 </p>
 
 <h2 class="rule">Authentication</h2>
@@ -47,20 +47,14 @@ The response may contain a JSON document with additional data.
 <div class="api-path">GET {{ SITE_ROOT }}/api/v1/checks/</div>
 
 <p>
-    Returns a list of checks
+    Returns a list of checks. This API call takes no parameters and returns
+    a JSON document with all checks in user's account.
 </p>
 <h3 class="api-section">Example Request</h3>
-
-<pre>
-curl {{ SITE_ROOT }}/api/v1/checks/ \
-    -X GET \
-    -d '{"api_key": "your-api-key"}'
-</pre>
+{% include "front/snippets/list_checks_request.html" %}
 
 <h3 class="api-section">Example Response</h3>
-<pre>
-{"checks": [{"url": "{{ PING_ENDPOINT }}848f3002-266b-482a-89ad-9d66a11aa2fb", "grace": 900, "name": "API test 1", "timeout": 3600, "tags": "foo"}, {"url": "{{ PING_ENDPOINT }}20324f81-5966-4e75-9734-8440df52ed75", "grace": 60, "name": "API test 2", "timeout": 60, "tags": "bar,baz"}]}
-</pre>
+{% include "front/snippets/list_checks_response.html" %}
 
 <h2 class="rule">Create a check</h2>
 
@@ -119,15 +113,9 @@ curl {{ SITE_ROOT }}/api/v1/checks/ \
 </table>
 
 <h3 class="api-section">Example Request</h3>
-<pre>
-curl {{ SITE_ROOT }}/api/v1/checks/ \
-    -X POST \
-    -d '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
-</pre>
+{% include "front/snippets/create_check_request.html" %}
 
 <h3 class="api-section">Example Response</h3>
-<pre>
-{"ping_url": "{{ PING_ENDPOINT }}20f2d3d0-efe4-4cc1-a114-a186a225de50"}
-</pre>
+{% include "front/snippets/create_check_response.html" %}
 
 {% endblock %}

templates/front/snippets/bash.html

@@ -1,6 +1,6 @@
-<div class="highlight"><pre><span class="c"># using curl:</span>
+<div class="highlight"><pre><span></span><span class="c1"># using curl:</span>
 curl --retry <span class="m">3</span> {{ ping_url }}
 
-<span class="c"># using wget:</span>
+<span class="c1"># using wget:</span>
 wget {{ ping_url }} -O /dev/null
 </pre></div>

templates/front/snippets/browser.html

@@ -1,4 +1,4 @@
-<div class="highlight"><pre><span class="kd">var</span> <span class="nx">xhr</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">XMLHttpRequest</span><span class="p">();</span>
+<div class="highlight"><pre><span></span><span class="kd">var</span> <span class="nx">xhr</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">XMLHttpRequest</span><span class="p">();</span>
 <span class="nx">xhr</span><span class="p">.</span><span class="nx">open</span><span class="p">(</span><span class="s1">&#39;GET&#39;</span><span class="p">,</span> <span class="s1">&#39;{{ ping_url }}&#39;</span><span class="p">,</span> <span class="kc">true</span><span class="p">);</span>
 <span class="nx">xhr</span><span class="p">.</span><span class="nx">send</span><span class="p">(</span><span class="kc">null</span><span class="p">);</span>
 </pre></div>

templates/front/snippets/create_check_request.html

@@ -0,0 +1,4 @@
+<div class="highlight"><pre><span></span>curl http://localhost:8000/api/v1/checks/ <span class="se">\</span>
+    -X POST <span class="se">\</span>
+    -d <span class="s1">&#39;{&quot;api_key&quot;: &quot;your-api-key&quot;, &quot;name&quot;: &quot;Backups&quot;, &quot;tags&quot;: &quot;prod www&quot;, &quot;timeout&quot;: 3600, &quot;grace&quot;: 60}&#39;</span>
+</pre></div>

templates/front/snippets/create_check_request.txt

@@ -0,0 +1,3 @@
+curl http://localhost:8000/api/v1/checks/ \
+    -X POST \
+    -d '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'

templates/front/snippets/create_check_response.html

@@ -0,0 +1,4 @@
+<div class="highlight"><pre><span></span><span class="p">{</span>
+  <span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;{{ PING_ENDPOINT }}20f2d3d0-efe4-4cc1-a114-a186a225de50&quot;</span>
+<span class="p">}</span>
+</pre></div>

templates/front/snippets/create_check_response.txt

@@ -0,0 +1,3 @@
+{
+  "ping_url": "PING_ENDPOINT20f2d3d0-efe4-4cc1-a114-a186a225de50"
+}

templates/front/snippets/crontab.html

@@ -1,3 +1,3 @@
-<div class="highlight"><pre><span class="c"># m h dom mon dow   command</span>
+<div class="highlight"><pre><span></span><span class="c1"># m h dom mon dow   command</span>
   <span class="m">8</span> <span class="m">6</span> *   *   *     /home/user/backup.sh <span class="o">&amp;&amp;</span> curl -fsS --retry <span class="m">3</span> {{ ping_url }} &gt; /dev/null
 </pre></div>

templates/front/snippets/list_checks_request.html

@@ -0,0 +1,4 @@
+<div class="highlight"><pre><span></span>curl {{ SITE_ROOT }}/api/v1/checks/ <span class="se">\</span>
+    -X GET <span class="se">\</span>
+    -d <span class="s1">&#39;{&quot;api_key&quot;: &quot;your-api-key&quot;}&#39;</span>
+</pre></div>

templates/front/snippets/list_checks_request.txt

@@ -0,0 +1,3 @@
+curl SITE_ROOT/api/v1/checks/ \
+    -X GET \
+    -d '{"api_key": "your-api-key"}'

templates/front/snippets/list_checks_response.html

@@ -0,0 +1,19 @@
+<div class="highlight"><pre><span></span><span class="p">{</span>
+  <span class="nt">&quot;checks&quot;</span><span class="p">:</span> <span class="p">[</span>
+    <span class="p">{</span>
+      <span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;{{ PING_ENDPOINT }}848f3002-266b-482a-89ad-9d66a11aa2fb&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">900</span><span class="p">,</span>
+      <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;API test 1&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;timeout&quot;</span><span class="p">:</span> <span class="mi">3600</span><span class="p">,</span>
+      <span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;foo&quot;</span>
+    <span class="p">},</span>
+    <span class="p">{</span>
+      <span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;{{ PING_ENDPOINT }}20324f81-5966-4e75-9734-8440df52ed75&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">60</span><span class="p">,</span>
+      <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;API test 2&quot;</span><span class="p">,</span>
+      <span class="nt">&quot;timeout&quot;</span><span class="p">:</span> <span class="mi">60</span><span class="p">,</span>
+      <span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;bar,baz&quot;</span>
+    <span class="p">}</span>
+  <span class="p">]</span>
+<span class="p">}</span>
+</pre></div>

templates/front/snippets/list_checks_response.txt

@@ -0,0 +1,18 @@
+{
+  "checks": [
+    {
+      "ping_url": "PING_ENDPOINT848f3002-266b-482a-89ad-9d66a11aa2fb",
+      "grace": 900,
+      "name": "API test 1",
+      "timeout": 3600,
+      "tags": "foo"
+    },
+    {
+      "ping_url": "PING_ENDPOINT20324f81-5966-4e75-9734-8440df52ed75",
+      "grace": 60,
+      "name": "API test 2",
+      "timeout": 60,
+      "tags": "bar,baz"
+    }
+  ]
+}

templates/front/snippets/node.html

@@ -1,3 +1,3 @@
-<div class="highlight"><pre><span class="kd">var</span> <span class="nx">http</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;http&#39;</span><span class="p">);</span>
+<div class="highlight"><pre><span></span><span class="kd">var</span> <span class="nx">http</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;http&#39;</span><span class="p">);</span>
 <span class="nx">http</span><span class="p">.</span><span class="nx">get</span><span class="p">(</span><span class="s2">&quot;{{ ping_url }}&quot;</span><span class="p">);</span>
 </pre></div>

templates/front/snippets/php.html

@@ -1,2 +1,2 @@
-<div class="highlight"><pre><span class="x">file_get_contents(&#39;{{ ping_url }}&#39;);</span>
+<div class="highlight"><pre><span></span><span class="x">file_get_contents(&#39;{{ ping_url }}&#39;);</span>
 </pre></div>

templates/front/snippets/powershell.html

@@ -1,2 +1,2 @@
-<div class="highlight"><pre><span class="nb">Invoke-RestMethod</span> <span class="n">{{ ping_url }}</span>
+<div class="highlight"><pre><span></span><span class="nb">Invoke-RestMethod</span> <span class="n">{{ ping_url }}</span>
 </pre></div>

templates/front/snippets/python.html

@@ -1,8 +1,8 @@
-<div class="highlight"><pre><span class="o">&gt;&gt;&gt;</span> <span class="c"># using urllib2:</span>
+<div class="highlight"><pre><span></span><span class="o">&gt;&gt;&gt;</span> <span class="c1"># using urllib2:</span>
 <span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">urllib2</span>
-<span class="o">&gt;&gt;&gt;</span> <span class="n">urllib2</span><span class="o">.</span><span class="n">urlopen</span><span class="p">(</span><span class="s">&quot;{{ ping_url }}&quot;</span><span class="p">)</span>
+<span class="o">&gt;&gt;&gt;</span> <span class="n">urllib2</span><span class="o">.</span><span class="n">urlopen</span><span class="p">(</span><span class="s2">&quot;{{ ping_url }}&quot;</span><span class="p">)</span>
 
-<span class="o">&gt;&gt;&gt;</span> <span class="c"># using requests:</span>
+<span class="o">&gt;&gt;&gt;</span> <span class="c1"># using requests:</span>
 <span class="o">&gt;&gt;&gt;</span> <span class="kn">import</span> <span class="nn">requests</span>
-<span class="o">&gt;&gt;&gt;</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">&quot;{{ ping_url }}&quot;</span><span class="p">)</span>
+<span class="o">&gt;&gt;&gt;</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;{{ ping_url }}&quot;</span><span class="p">)</span>
 </pre></div>