users_guide: Convert mkUserGuidePart generation to a Sphinx extension

Authored by patrickdoc on Aug 18 2017, 8:20 AM.

Description

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 Trac #11654 and, incidentally, Trac #12155.

Reviewers: austin, bgamari

Subscribers: rwbarton, thomie

GHC Trac Issues: Trac #11654, Trac #12155

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