Improve presentation of push rules kinds and actions (#1348)

assets/scss/custom.scss

@@ -474,3 +474,31 @@ Make padding symmetrical (this selector is used in the default styles to apply p
   background-repeat: no-repeat;
   padding-left: 100px;
 }
+
+/* Adjust the styling of definition lists. */
+
+/* Add a little spacing between the term and its definition. */
+dt {
+   margin-bottom: 0.15rem;
+}
+
+/* _reboot.scss deliberately sets margin-left to 0. Undo this. */
+dd {
+  margin-left: 2rem;
+}
+
+/* docsy's _code.scss does only styles <code> elements matching
+ * .td-content { p code, li > code, table code }.
+ * Copy those styles here to apply to code <elements> in definition terms too. */
+
+.td-content {
+  dt code {
+    color: inherit;
+    padding: 0.2em 0.4em;
+    margin: 0;
+    font-size: 85%;
+    word-break: normal;
+    background-color: rgba($black, 0.05);
+    border-radius: 0.25rem;  // was $border-radius, but that var isn't accessible here.
+  }
+}

changelogs/client_server/newsfragments/1348.clarification

@@ -0,0 +1 @@
+Improve the presentation of push rule kinds and actions.

content/client-server-api/modules/push.md

@@ -144,25 +144,25 @@ the value of `kind`.
 
 The different `kind`s of rule, in the order that they are checked, are:
 
-Override Rules `override`
+1.  **Override rules (`override`).**
     The highest priority rules are user-configured overrides.
 
-Content-specific Rules `content`
+1.  **Content-specific rules (`content`).**
     These configure behaviour for (unencrypted) messages that match certain
     patterns. Content rules take one parameter: `pattern`, that gives the
     glob pattern to match against. This is treated in the same way as
     `pattern` for `event_match`.
 
-Room-specific Rules `room`
+1.  **Room-specific rules (`room`).**
     These rules change the behaviour of all messages for a given room. The
     `rule_id` of a room rule is always the ID of the room that it affects.
 
-Sender-specific rules `sender`
+1.  **Sender-specific rules (`sender`).**
     These rules configure notification behaviour for messages from a
     specific Matrix user ID. The `rule_id` of Sender rules is always the
     Matrix user ID of the user whose messages they'd apply to.
 
-Underride rules `underride`
+1.  **Underride rules (`underride`).**
     These are identical to `override` rules, but have a lower priority than
     `content`, `room` and `sender` rules.
 
@@ -186,19 +186,23 @@ how a notification is delivered for a matching event. The following
 actions are defined:
 
 `notify`
-This causes each matching event to generate a notification.
+
+:   This causes each matching event to generate a notification.
 
 `dont_notify`
-This prevents each matching event from generating a notification
+
+:   This prevents each matching event from generating a notification.
 
 `coalesce`
-This enables notifications for matching events but activates homeserver
+
+:   This enables notifications for matching events but activates homeserver
     specific behaviour to intelligently coalesce multiple events into a
     single notification. Not all homeservers may support this. Those that do
     not support it should treat it as the `notify` action.
 
 `set_tweak`
-Sets an entry in the `tweaks` dictionary key that is sent in the
+
+:   Sets an entry in the `tweaks` dictionary key that is sent in the
     notification request to the Push Gateway. This takes the form of a
     dictionary with a `set_tweak` key whose value is the name of the tweak
     to set. It may also have a `value` key which is the value to which it
@@ -206,12 +210,16 @@ should be set.
 
     The following tweaks are defined:
 
-* `sound`: A string representing the sound to be played when this notification
+    `sound`
+
+    :   A string representing the sound to be played when this notification
         arrives. A value of `default` means to play a default sound. A device
         may choose to alert the user by some other means if appropriate, eg.
         vibration.
 
-* `highlight`: A boolean representing whether or not this message should be highlighted
+    `highlight`
+
+    :   A boolean representing whether or not this message should be highlighted
         in the UI. This will normally take the form of presenting the message in
         a different colour and/or style. The UI might also be adjusted to draw
         particular attention to the room in which the event occurred. If a
@@ -227,7 +235,7 @@ light on a mobile device.
 Actions that have no parameters are represented as a string. Otherwise,
 they are represented as a dictionary with a key equal to their name and
 other keys as their parameters, e.g.
-`{ "set_tweak": "sound", "value": "default" }`
+`{ "set_tweak": "sound", "value": "default" }`.
 
 ###### Conditions