users_guide: Convert mkUserGuidePart generation to a Sphinx extension

This removes all dependencies the users guide had on `mkUserGuidePart`.
The generation of the flag reference table and the various pieces of the
man page is now entirely contained within the Spinx extension
`flags.py`. You can see the man page generation on the orphan page
https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/ghc.html

The extension works by collecting all of the meta-data attached to the
`ghc-flag` directives and then formatting and displaying it at
`flag-print` directives. There is a single printing directive that can
be customized with two options, what format to display (table, list, or
block of flags) and an optional category to limit the output to
(verbosity, warnings, codegen, etc.).

New display formats can be added by creating a function
`generate_flag_xxx` (where `xxx` is a description of the format) which
takes a list of flags and a category and returns a new `xxx`. Then just
add a reference in the dispatch table `handlers`. That display can now
be run by passing `:type: xxx` to the `flag-print` directive.

`flags.py` contains two maps of settings that can be adjusted. The first
is a canonical list of flag categories, and the second sets default
categories for files.

The only functionality that Sphinx could not replace was the
`what_glasgow_exts_does.gen.rst` file. `mkUserGuidePart` actually just
reads the list of flags from `compiler/main/DynFlags.hs` which Sphinx
cannot do. As the flag is deprecated, I added the list as a static file
which can be updated manually.

Additionally, this patch updates every single documented flag with the
data from `mkUserGuidePart` to generate the reference table.

Fixes #11654 and, incidentally, #12155.

Reviewers: austin, bgamari

Subscribers: rwbarton, thomie

GHC Trac Issues: #11654, #12155

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

1 files changed, 50 insertions, 10 deletions

diff --git a/docs/users_guide/safe_haskell.rst b/docs/users_guide/safe_haskell.rst
index e1238a8e2c..7be442e036 100644
--- a/docs/users_guide/safe_haskell.rst
+++ b/docs/users_guide/safe_haskell.rst
@@ -562,10 +562,10 @@ Trustworthy Requirements
 .. index::
    single: trustworthy
 
-Module authors using the :ghc-flag:`-XTrustworthy` language extension for a module ``M``
-should ensure that ``M``\'s public API (the symbols exposed by its export list)
-can't be used in an unsafe manner. This mean that symbols exported should
-respect type safety and referential transparency.
+Module authors using the :ghc-flag:`-XTrustworthy` language extension for a
+module ``M`` should ensure that ``M``\'s public API (the symbols exposed by its
+export list) can't be used in an unsafe manner. This mean that symbols exported
+should respect type safety and referential transparency.
 
 .. _safe-package-trust:
 
@@ -580,19 +580,30 @@ Several new options are available at the GHC command-line to specify the
 trust property of packages:
 
 .. ghc-flag:: -trust ⟨pkg⟩
+    :shortdesc: Expose package ⟨pkg⟩ and set it to be trusted. See
+        :ref:`safe-haskell`.
+    :type: dynamic/ ``:set``
+    :category:
 
-   Exposes package ⟨pkg⟩ if it was hidden and considers it a
-   trusted package regardless of the package database.
+    Exposes package ⟨pkg⟩ if it was hidden and considers it a
+    trusted package regardless of the package database.
 
 .. ghc-flag:: -distrust ⟨pkg⟩
+    :shortdesc: Expose package ⟨pkg⟩ and set it to be distrusted. See
+        :ref:`safe-haskell`.
+    :type: dynamic/ ``:set``
+    :category:
 
-   Exposes package ⟨pkg⟩ if it was hidden and considers it
-   an untrusted package regardless of the package database.
+    Exposes package ⟨pkg⟩ if it was hidden and considers it
+    an untrusted package regardless of the package database.
 
 .. ghc-flag:: -distrust-all-packages
+    :shortdesc: Distrust all packages by default. See :ref:`safe-haskell`.
+    :type: dynamic/ ``:set``
+    :category:
 
-   Considers all packages distrusted unless they are
-   explicitly set to be trusted by subsequent command-line options.
+    Considers all packages distrusted unless they are
+    explicitly set to be trusted by subsequent command-line options.
 
 To set a package's trust property in the package database please refer
 to :ref:`packages`.
@@ -647,6 +658,9 @@ Safe Haskell Flag Summary
 In summary, Safe Haskell consists of the following three language flags:
 
 .. ghc-flag:: -XSafe
+    :shortdesc: Enable the :ref:`Safe Haskell <safe-haskell>` Safe mode.
+    :type: dynamic
+    :category:
 
     :since: 7.2.1
 
@@ -662,6 +676,9 @@ In summary, Safe Haskell consists of the following three language flags:
     - *Imported Modules* — All forced to be safe imports, all must be trusted.
 
 .. ghc-flag:: -XTrustworthy
+    :shortdesc: Enable the :ref:`Safe Haskell <safe-haskell>` Trustworthy mode.
+    :type: dynamic
+    :category:
 
     :since: 7.2.1
 
@@ -683,6 +700,9 @@ In summary, Safe Haskell consists of the following three language flags:
       trusted.
 
 .. ghc-flag:: -XUnsafe
+    :shortdesc: Enable :ref:`Safe Haskell <safe-haskell>` Unsafe mode.
+    :type: dynamic
+    :category:
 
     :since: 7.4.1
 
@@ -699,6 +719,11 @@ In summary, Safe Haskell consists of the following three language flags:
 And one general flag:
 
 .. ghc-flag:: -fpackage-trust
+    :shortdesc: Enable :ref:`Safe Haskell <safe-haskell>` trusted package
+        requirement for trustworthy modules.
+    :type: dynamic
+    :category:
+
     When enabled, turn on an extra check for a trustworthy module ``M``,
     requiring the package that ``M`` resides in be considered trusted, for ``M``
     to be considered trusted.
@@ -706,18 +731,33 @@ And one general flag:
 And three warning flags:
 
 .. ghc-flag:: -Wunsafe
+    :shortdesc: warn if the module being compiled is regarded to be unsafe.
+        See :ref:`safe-haskell`
+    :type: dynamic
+    :reverse: -Wno-unsafe
+    :category:
 
     Issue a warning if the module being compiled is regarded to be
     unsafe. Should be used to check the safety type of modules when
     using safe inference.
 
 .. ghc-flag:: -Wsafe
+    :shortdesc: warn if the module being compiled is regarded to be safe.
+    :type: dynamic
+    :reverse: -Wno-safe
+    :category:
 
     Issue a warning if the module being compiled is regarded to be safe.
     Should be used to check the safety type of modules when using safe
     inference.
 
 .. ghc-flag:: -Wtrustworthy-safe
+    :shortdesc: warn if the module being compiled is marked as
+        :ghc-flag:`-XTrustworthy` but it could instead be marked as
+        :ghc-flag:`-XSafe`, a more informative bound.
+    :type: dynamic
+    :reverse: -Wno-safe
+    :category:
 
     Issue a warning if the module being compiled is marked as
     -XTrustworthy but it could instead be marked as