[commit: ghc] master: users_guide: Convert mkUserGuidePart generation to a Sphinx extension (cf8ab1c)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/cf8ab1ced6f15dad03dd7bcc454ef759cf4d3b3d/ghc

>---------------------------------------------------------------

commit cf8ab1ced6f15dad03dd7bcc454ef759cf4d3b3d
Author: Patrick Dougherty <patrick.doc at ameritech.net>
Date:   Fri Aug 18 09:20:07 2017 -0400

    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


>---------------------------------------------------------------

cf8ab1ced6f15dad03dd7bcc454ef759cf4d3b3d
 .gitignore                                  |   2 +-
 compiler/main/DynFlags.hs                   |   1 +
 docs/users_guide/conf.py                    |  15 +-
 docs/users_guide/debug-info.rst             |   5 +
 docs/users_guide/debugging.rst              | 232 ++++++++++-
 docs/users_guide/editing-guide.rst          |  28 +-
 docs/users_guide/extending_ghc.rst          |  20 +-
 docs/users_guide/ffi-chap.rst               |  22 ++
 docs/users_guide/flags.py                   | 400 +++++++++++++++++++
 docs/users_guide/flags.rst                  | 269 +++++++++++--
 docs/users_guide/ghc.mk                     |   6 +-
 docs/users_guide/ghc.rst                    | 312 ++++++++++++++-
 docs/users_guide/ghci.rst                   |  66 +++-
 docs/users_guide/glasgow_exts.rst           | 578 +++++++++++++++++++++++++++-
 docs/users_guide/packages.rst               |  57 ++-
 docs/users_guide/phases.rst                 | 229 +++++++++++
 docs/users_guide/profiling.rst              |  44 ++-
 docs/users_guide/safe_haskell.rst           |  60 ++-
 docs/users_guide/separate_compilation.rst   | 117 +++++-
 docs/users_guide/using-concurrent.rst       |   4 +
 docs/users_guide/using-optimisation.rst     | 285 +++++++++++++-
 docs/users_guide/using-warnings.rst         | 432 +++++++++++++++++++--
 docs/users_guide/using.rst                  | 159 +++++++-
 docs/users_guide/what_glasgow_exts_does.rst |  33 ++
 24 files changed, 3226 insertions(+), 150 deletions(-)

Diff suppressed because of size. To see it, use:

    git diff-tree --root --patch-with-stat --no-color --find-copies-harder --ignore-space-at-eol --cc cf8ab1ced6f15dad03dd7bcc454ef759cf4d3b3d