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.