users-guide: Standardize and repair all flag references

This patch does three things:

1.) It simplifies the flag parsing code in `conf.py` to properly display
flag definitions created by `.. (ghc|rts)-flag::`. Additionally, all flag
references must include the associated arguments. Documentation has been
added to `editing-guide.rst` to explain this.

2.) It normalizes all flag definitions to a similar format. Notably, all
instances of `<>` have been replaced with `⟨⟩`. All references across the
users guide have been updated to match.

3.) It fixes a couple issues with the flag reference table's generation code,
which did not handle comma separated flags in the same cell and did not
properly reference flags with arguments.

Test Plan:
`SPHINXOPTS = -n` to activate "nitpicky" mode, which reports all broken
references. All remaining errors are references to flags without any
documentation.

Reviewers: austin, bgamari

Reviewed By: bgamari

Subscribers: rwbarton, thomie

GHC Trac Issues: #13980

Differential Revision: https://phabricator.haskell.org/D3778

1 files changed, 28 insertions, 24 deletions

diff --git a/docs/users_guide/conf.py b/docs/users_guide/conf.py
index 8a4c18f53e..12ecee9beb 100644
--- a/docs/users_guide/conf.py
+++ b/docs/users_guide/conf.py
@@ -116,35 +116,39 @@ texinfo_documents = [
 from sphinx import addnodes
 from docutils import nodes
 
+# The following functions parse flag declarations, and then have two jobs. First
+# they modify the docutils node `signode` for the proper display of the
+# declaration. Second, they return the name used to reference the flag.
+# (i.e. return "name" implies you reference the flag with :flag:`name`)
 def parse_ghci_cmd(env, sig, signode):
-    name = sig.split(';')[0]
-    sig = sig.replace(';', '')
-    signode += addnodes.desc_name(name, sig)
+    parts = sig.split(';')
+    name = parts[0]
+    args = ''
+    if len(parts) > 1:
+        args = parts[1]
+    # Bold name
+    signode += addnodes.desc_name(name, name)
+    # Smaller args
+    signode += addnodes.desc_addname(args, args)
+    # Reference name
     return name
 
 def parse_flag(env, sig, signode):
+
+    # Break flag into name and args
     import re
-    names = []
-    for i, flag in enumerate(sig.split(',')):
-        flag = flag.strip()
-        sep = '='
-        parts = flag.split('=')
-        if len(parts) == 1:
-            sep=' '
-            parts = flag.split()
-        if len(parts) == 0: continue
-
-        name = parts[0]
-        names.append(name)
-        sig = sep + ' '.join(parts[1:])
-        sig = re.sub(ur'<([-a-zA-Z ]+)>', ur'⟨\1⟩', sig)
-        if i > 0:
-            signode += addnodes.desc_name(', ', ', ')
-        signode += addnodes.desc_name(name, name)
-        if len(sig) > 0:
-            signode += addnodes.desc_addname(sig, sig)
-
-    return names[0]
+    parts = re.split('( |=|\\[)', sig, 1)
+    flag = parts[0]
+    args = ''
+    if len(parts) > 1:
+        args = ''.join(parts[1:])
+
+    # Bold printed name
+    signode += addnodes.desc_name(flag, flag)
+    # Smaller arguments
+    signode += addnodes.desc_addname(args, args)
+    # Reference name left unchanged
+    return sig
 
 def setup(app):
     from sphinx.util.docfields import Field, TypedField