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, 19 insertions, 1 deletions

diff --git a/docs/users_guide/extending_ghc.rst b/docs/users_guide/extending_ghc.rst
index 4a3e02e83e..e9543ebce5 100644
--- a/docs/users_guide/extending_ghc.rst
+++ b/docs/users_guide/extending_ghc.rst
@@ -196,13 +196,22 @@ module in a registered package that exports a plugin. Arguments can be given to
 plugins with the :ghc-flag:`-fplugin-opt=⟨module⟩:⟨args⟩` option.
 
 .. ghc-flag:: -fplugin=⟨module⟩
+    :shortdesc: Load a plugin exported by a given module
+    :type: dynamic
+    :category: plugins
 
     Load the plugin in the given module. The module must be a member of a
     package registered in GHC's package database.
 
 .. ghc-flag:: -fplugin-opt=⟨module⟩:⟨args⟩
+    :shortdesc: Give arguments to a plugin module; module must be specified with
+        :ghc-flag:`-fplugin=⟨module⟩`
+    :type: dynamic
+    :category: plugins
+
+    Give arguments to a plugin module; module must be specified with
+    :ghc-flag:`-fplugin=⟨module⟩`.
 
-    Pass arguments ⟨args⟩ to the given plugin.
 
 As an example, in order to load the plugin exported by ``Foo.Plugin`` in
 the package ``foo-ghc-plugin``, and give it the parameter "baz", we
@@ -227,6 +236,9 @@ the same; however, there are a few command line options which
 control specifically plugin packages:
 
 .. ghc-flag:: -plugin-package ⟨pkg⟩
+    :shortdesc: Expose ⟨pkg⟩ for plugins
+    :type: dynamic
+    :category: plugins
 
     This option causes the installed package ⟨pkg⟩ to be exposed for plugins,
     such as :ghc-flag:`-fplugin=⟨module⟩`. The package ⟨pkg⟩ can be specified
@@ -241,6 +253,9 @@ control specifically plugin packages:
     to be linked into the resulting executable or shared object.
 
 .. ghc-flag:: -plugin-package-id ⟨pkg-id⟩
+    :shortdesc: Expose ⟨pkg-id⟩ for plugins
+    :type: dynamic
+    :category: plugins
 
     Exposes a package in the plugin namespace like :ghc-flag:`-plugin-package
     ⟨pkg⟩`, but the package is named by its installed package ID rather than by
@@ -251,6 +266,9 @@ control specifically plugin packages:
     described in :ref:`package-thinning-and-renaming`.
 
 .. ghc-flag:: -hide-all-plugin-packages
+    :shortdesc: Hide all packages for plugins by default
+    :type: dynamic
+    :category: plugins
 
     By default, all exposed packages in the normal, source import namespace are
     also available for plugins.  This causes those packages to be hidden by