[GHC] #11654: User Guide: Generate command line options table from ghc-flags directives

[GHC]

#11654: User Guide: Generate command line options table from ghc-flags directives
-------------------------------------+-------------------------------------
        Reporter:  bgamari           |                Owner:  patrickdoc
            Type:  task              |               Status:  patch
        Priority:  normal            |            Milestone:  8.4.1
       Component:  Documentation     |              Version:  7.10.3
      Resolution:                    |             Keywords:
Operating System:  Unknown/Multiple  |         Architecture:
                                     |  Unknown/Multiple
 Type of failure:  None/Unknown      |            Test Case:
      Blocked By:                    |             Blocking:
 Related Tickets:                    |  Differential Rev(s):  Phab:D3839
       Wiki Page:                    |
-------------------------------------+-------------------------------------

Comment (by Ben Gamari <ben@…>):

 In [changeset:"cf8ab1ced6f15dad03dd7bcc454ef759cf4d3b3d/ghc"
 cf8ab1ce/ghc]:
 {{{
 #!CommitTicketReference repository="ghc"
 revision="cf8ab1ced6f15dad03dd7bcc454ef759cf4d3b3d"
 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
 }}}

-- 
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11654#comment:10>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler