Improve docs

templates/docs/http_api.html

@@ -22,13 +22,15 @@ or by a combination of project's Ping Key and check's slug.</p>
 immutable. You cannot replace the automatically assigned UUID with a manually
 chosen one. When you delete a check, you also lose its UUID and cannot get it back.</p>
 <p>You can look up UUIDs of your checks in web UI or via <a href="../api/">Management API</a> calls.</p>
-<p><strong>Check's slug</strong> is its name with the following transformations applied:</p>
+<p><strong>Check's slug</strong> is derived from check's name using Django's
+<a href="https://docs.djangoproject.com/en/3.2/ref/utils/#django.utils.text.slugify">slugify</a>
+function. It applies the following transformations:</p>
 <ul>
 <li>Convert to ASCII.</li>
 <li>Convert to lowercase.</li>
 <li>Remove characters that aren't alphanumerics, underscores, hyphens, or whitespace.</li>
-<li>Replace any whitespace or repeated dashes with single dashes.</li>
-<li>Remove leading and trailing whitespace, dashes, and underscores.</li>
+<li>Replace any whitespace or repeated hyphens with single hyphens.</li>
+<li>Remove leading and trailing whitespace, hyphens, and underscores.</li>
 </ul>
 <p>For example, if check's name is "Database Backup", its slug is <code>database-backup</code>.</p>
 <p>Check's slug <strong>can change</strong>. SITE_NAME updates check's slug whenever its name changes.</p>

templates/docs/http_api.md

@@ -30,13 +30,15 @@ chosen one. When you delete a check, you also lose its UUID and cannot get it ba
 
 You can look up UUIDs of your checks in web UI or via [Management API](../api/) calls.
 
-**Check's slug** is its name with the following transformations applied:
+**Check's slug** is derived from check's name using Django's
+[slugify](https://docs.djangoproject.com/en/3.2/ref/utils/#django.utils.text.slugify)
+function. It applies the following transformations:
 
 * Convert to ASCII.
 * Convert to lowercase.
 * Remove characters that aren't alphanumerics, underscores, hyphens, or whitespace.
-* Replace any whitespace or repeated dashes with single dashes.
-* Remove leading and trailing whitespace, dashes, and underscores.
+* Replace any whitespace or repeated hyphens with single hyphens.
+* Remove leading and trailing whitespace, hyphens, and underscores.
 
 For example, if check's name is "Database Backup", its slug is `database-backup`.
 

templates/docs/introduction.html

@@ -60,20 +60,21 @@ workers, batch scripts, scheduled tasks, web services) make HTTP requests to the
 ping URL to signal a start of the execution, a success, or a failure.</p>
 <p>SITE_NAME supports two ping URL formats:</p>
 <ul>
-<li><code>PING_ENDPOINT{uuid}</code><br>
+<li><code>PING_ENDPOINT&lt;uuid&gt;</code><br>
 The check is identified by its UUID. Check UUIDs are assigned
 automatically by SITE_NAME, and are guaranteed to be unique.</li>
-<li><code>PING_ENDPOINT{project-ping-key}/{name-slug}</code><br>
+<li><code>PING_ENDPOINT&lt;project-ping-key&gt;/&lt;name-slug&gt;</code><br>
 The check is identified by project's <strong>Ping key</strong> and check's
 <strong>slug</strong> (its name, converted to lowercase, spaces replaced with hyphens).</li>
 </ul>
-<p>You can append <code>/start</code>, <code>/fail</code> or <code>/{exitcode}</code> to the base ping URL to send
+<p>You can append <code>/start</code>, <code>/fail</code> or <code>/&lt;exitcode&gt;</code> to the base ping URL to send
 "start" and "failure" signals. The "start" and "failure" signals are optional.
 You don't have to use them, but you can gain additional monitoring insights
 if you do use them. See <a href="measuring_script_run_time/">Measuring script run time</a> and
 <a href="signaling_failures/">Signaling failures</a> for details.</p>
 <p>You should treat check UUIDs and project Ping keys as secrets. If you make them public,
 anybody can send telemetry signals to your checks and mess with your monitoring.</p>
+<p>Read more about Ping URLs in <a href="http_api/">Pinging API</a>.</p>
 <hr />
 <p><strong>Grace Time</strong> is one of the configuration parameters you can set for each check.
 It is the additional time to wait before sending an alert when a check

templates/docs/introduction.md

@@ -70,14 +70,14 @@ ping URL to signal a start of the execution, a success, or a failure.
 
 SITE_NAME supports two ping URL formats:
 
-* `PING_ENDPOINT{uuid}`<br>
+* `PING_ENDPOINT<uuid>`<br>
 The check is identified by its UUID. Check UUIDs are assigned
 automatically by SITE_NAME, and are guaranteed to be unique.
-* `PING_ENDPOINT{project-ping-key}/{name-slug}`<br>
+* `PING_ENDPOINT<project-ping-key>/<name-slug>`<br>
 The check is identified by project's **Ping key** and check's
 **slug** (its name, converted to lowercase, spaces replaced with hyphens).
 
-You can append `/start`, `/fail` or `/{exitcode}` to the base ping URL to send
+You can append `/start`, `/fail` or `/<exitcode>` to the base ping URL to send
 "start" and "failure" signals. The "start" and "failure" signals are optional.
 You don't have to use them, but you can gain additional monitoring insights
 if you do use them. See [Measuring script run time](measuring_script_run_time/) and
@@ -86,6 +86,8 @@ if you do use them. See [Measuring script run time](measuring_script_run_time/)
 You should treat check UUIDs and project Ping keys as secrets. If you make them public,
 anybody can send telemetry signals to your checks and mess with your monitoring.
 
+Read more about Ping URLs in [Pinging API](http_api/).
+
 ---
 
 **Grace Time** is one of the configuration parameters you can set for each check.