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

diff --git a/docs/users_guide/packages.rst b/docs/users_guide/packages.rst
index c728acbd08..e31abc06a6 100644
--- a/docs/users_guide/packages.rst
+++ b/docs/users_guide/packages.rst
@@ -128,6 +128,9 @@ command (see :ref:`package-management`):
 The GHC command line options that control packages are:
 
 .. ghc-flag:: -package ⟨pkg⟩
+    :shortdesc: Expose package ⟨pkg⟩
+    :type: dynamic/ ``:set``
+    :category:
 
     This option causes the installed package ⟨pkg⟩ to be exposed. The
     package ⟨pkg⟩ can be specified in full with its version number (e.g.
@@ -177,6 +180,9 @@ The GHC command line options that control packages are:
         $ ghc -o myprog Foo.hs Main.hs -package network
 
 .. ghc-flag:: -package-id ⟨unit-id⟩
+    :shortdesc: Expose package by id ⟨unit-id⟩
+    :type: dynamic/ ``:set``
+    :category:
 
     Exposes a package like :ghc-flag:`-package ⟨pkg⟩`, but the package is named
     by its unit ID (i.e. the value of ``id`` in its entry in the installed
@@ -187,6 +193,9 @@ The GHC command line options that control packages are:
     renaming described in :ref:`package-thinning-and-renaming`.
 
 .. ghc-flag:: -hide-all-packages
+    :shortdesc: Hide all packages by default
+    :type: dynamic
+    :category:
 
     Ignore the exposed flag on installed packages, and hide them all by
     default. If you use this flag, then any packages you require
@@ -199,6 +208,9 @@ The GHC command line options that control packages are:
     ``-hide-all-packages`` flag to GHC, for exactly this reason.
 
 .. ghc-flag:: -hide-package ⟨pkg⟩
+    :shortdesc: Hide package ⟨pkg⟩
+    :type: dynamic/ ``:set``
+    :category:
 
     This option does the opposite of :ghc-flag:`-package ⟨pkg⟩`: it causes the
     specified package to be hidden, which means that none of its modules
@@ -209,6 +221,9 @@ The GHC command line options that control packages are:
     exposed package.
 
 .. ghc-flag:: -ignore-package ⟨pkg⟩
+    :shortdesc: Ignore package ⟨pkg⟩
+    :type: dynamic/ ``:set``
+    :category:
 
     Causes the compiler to behave as if package ⟨pkg⟩, and any packages
     that depend on ⟨pkg⟩, are not installed at all.
@@ -220,11 +235,18 @@ The GHC command line options that control packages are:
     :ghc-flag:`-ignore-package ⟨pkg⟩` flag can be useful.
 
 .. ghc-flag:: -no-auto-link-packages
+    :shortdesc: Don't automatically link in the base and rts packages.
+    :type: dynamic
+    :category:
 
     By default, GHC will automatically link in the ``base`` and ``rts``
     packages. This flag disables that behaviour.
 
 .. ghc-flag:: -this-unit-id ⟨unit-id⟩
+    :shortdesc: Compile to be part of unit (i.e. package)
+        ⟨unit-id⟩
+    :type: dynamic
+    :category:
 
     Tells GHC that the module being compiled forms part of unit ID
     ⟨unit-id⟩; internally, these keys are used to determine type equality
@@ -234,6 +256,10 @@ The GHC command line options that control packages are:
     way in later releases.
 
 .. ghc-flag:: -trust ⟨pkg⟩
+    :shortdesc: Expose package ⟨pkg⟩ and set it to be trusted
+    :type: dynamic/ ``:set``
+    :category:
+    :noindex:
 
     This option causes the install package ⟨pkg⟩ to be both exposed and
     trusted by GHC. This command functions in a very similar way
@@ -242,6 +268,10 @@ The GHC command line options that control packages are:
     package database. (see :ref:`safe-haskell`).
 
 .. ghc-flag:: -distrust ⟨pkg⟩
+    :shortdesc: Expose package ⟨pkg⟩ and set it to be distrusted
+    :type: dynamic/ ``:set``
+    :category:
+    :noindex:
 
     This option causes the install package ⟨pkg⟩ to be both exposed and
     distrusted by GHC. This command functions in a very similar way to the
@@ -249,7 +279,11 @@ The GHC command line options that control packages are:
     packages to be distrusted by GHC, regardless of the contents of the package
     database. (see :ref:`safe-haskell`).
 
-.. ghc-flag:: -distrust-all
+.. ghc-flag:: -distrust-all-packages
+    :shortdesc: Distrust all packages by default
+    :type: dynamic/ ``:set``
+    :category:
+    :noindex:
 
     Ignore the trusted flag on installed packages, and distrust them by
     default. If you use this flag and Safe Haskell then any packages you
@@ -397,19 +431,31 @@ You can control GHC's package database stack using the following
 options:
 
 .. ghc-flag:: -package-db ⟨file⟩
+    :shortdesc: Add ⟨file⟩ to the package db stack.
+    :type: dynamic
+    :category:
 
     Add the package database ⟨file⟩ on top of the current stack.
 
 .. ghc-flag:: -no-global-package-db
+    :shortdesc: Remove the global package db from the stack.
+    :type: dynamic
+    :category:
 
     Remove the global package database from the package database stack.
 
 .. ghc-flag:: -no-user-package-db
+    :shortdesc: Remove the user's package db from the stack.
+    :type: dynamic
+    :category:
 
     Prevent loading of the user's local package database in the initial
     stack.
 
 .. ghc-flag:: -clear-package-db
+    :shortdesc: Clear the package db stack.
+    :type: dynamic
+    :category:
 
     Reset the current package database stack. This option removes every
     previously specified package database (including those read from the
@@ -417,6 +463,9 @@ options:
     stack.
 
 .. ghc-flag:: -global-package-db
+    :shortdesc: Add the global package db to the stack.
+    :type: dynamic
+    :category:
 
     Add the global package database on top of the current stack. This
     option can be used after :ghc-flag:`-no-global-package-db` to specify the
@@ -424,6 +473,9 @@ options:
     loaded.
 
 .. ghc-flag:: -user-package-db
+    :shortdesc: Add the user's package db to the stack.
+    :type: dynamic
+    :category:
 
     Add the user's package database on top of the current stack. This
     option can be used after :ghc-flag:`-no-user-package-db` to specify the
@@ -521,6 +573,9 @@ Note that for the ``package-db`` directive, if a relative path is given it
 must be relative to the location of the package environment file.
 
 .. ghc-flag:: -package-env ⟨file⟩|⟨name⟩
+    :shortdesc: Use the specified package environment.
+    :type: dynamic
+    :category:
 
     Use the package environment in ⟨file⟩, or in
     ``$HOME/.ghc/arch-os-version/environments/⟨name⟩``