Bug 1636304. Fix and improve the Mermaid documentation. r=sylvestre

The second example, when copied and pasted, is completely borked since it
is not preceeded by the line that declares what follows to be a Mermaid
diagram. This change fixes that.

It also fixes the prose to read slightly less awkwardly in places.

Finally, this change also adds a link to the Mermaid Live Editor to make
readers aware of this useful tool.

Differential Revision: https://phabricator.services.mozilla.com/D74338

tools/moztreedocs/docs/mermaid-integration.rst

@@ -1,12 +1,15 @@
 Mermaid Integration
 ===================
 
-Mermaid is a tool that lets you generate flow charts, sequence diagrams, gantt charts, class diagrams and vcs graphs from a simple markup language. This
-means you can embed these directly in the source rather than creating an image
-with some external tool and then checking it into the tree. To add a diagram,
-simply put something like this into your page:
+Mermaid is a tool that lets you generate flow charts, sequence diagrams, gantt
+charts, class diagrams and vcs graphs from a simple markup language. This
+allows charts and diagrams to be embedded and edited directly in the
+documentation source files rather than creating them as images using some
+external tool and checking the images into the tree.
 
-.. These two examples are coming from the upstream website (https://mermaid-js.github.io/mermaid/#/)
+To add a diagram, simply put something like this into your page:
+
+.. These two examples come from the upstream website (https://mermaid-js.github.io/mermaid/#/)
 
 .. code-block:: shell
 
@@ -32,17 +35,19 @@ Or
 
 .. code-block:: shell
 
-     sequenceDiagram
-         participant Alice
-         participant Bob
-         Alice->>John: Hello John, how are you?
-         loop Healthcheck
-             John->>John: Fight against hypochondria
-         end
-         Note right of John: Rational thoughts <br/>prevail!
-         John-->>Alice: Great!
-         John->>Bob: How about you?
-         Bob-->>John: Jolly good!
+    .. mermaid::
+
+         sequenceDiagram
+             participant Alice
+             participant Bob
+             Alice->>John: Hello John, how are you?
+             loop Healthcheck
+                 John->>John: Fight against hypochondria
+             end
+             Note right of John: Rational thoughts <br/>prevail!
+             John-->>Alice: Great!
+             John->>Bob: How about you?
+             Bob-->>John: Jolly good!
 
 will show:
 
@@ -61,4 +66,7 @@ will show:
          Bob-->>John: Jolly good!
 
 
-See `mermaid's official <https://mermaid-js.github.io/mermaid/#/>`__ docs for more details on the syntax.
+See `Mermaid's official <https://mermaid-js.github.io/mermaid/#/>`__ docs for
+more details on the syntax, and use the
+`Mermaid Live Editor <https://mermaidjs.github.io/mermaid-live-editor>`__ to
+experiment with creating your own diagrams.