1. 16 Oct, 2017 1 commit
  2. 26 Sep, 2017 1 commit
  3. 19 Aug, 2017 1 commit
    • patrickdoc's avatar
      users_guide: Convert mkUserGuidePart generation to a Sphinx extension · cf8ab1ce
      patrickdoc authored and Ben Gamari's avatar Ben Gamari committed
      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
      cf8ab1ce
  4. 24 Jul, 2017 1 commit
  5. 23 Jul, 2017 1 commit
    • patrickdoc's avatar
      users-guide: Standardize and repair all flag references · 44b090be
      patrickdoc authored and Ben Gamari's avatar Ben Gamari committed
      This patch does three things:
      
      1.) It simplifies the flag parsing code in `conf.py` to properly display
      flag definitions created by `.. (ghc|rts)-flag::`. Additionally, all flag
      references must include the associated arguments. Documentation has been
      added to `editing-guide.rst` to explain this.
      
      2.) It normalizes all flag definitions to a similar format. Notably, all
      instances of `<>` have been replaced with `⟨⟩`. All references across the
      users guide have been updated to match.
      
      3.) It fixes a couple issues with the flag reference table's generation code,
      which did not handle comma separated flags in the same cell and did not
      properly reference flags with arguments.
      
      Test Plan:
      `SPHINXOPTS = -n` to activate "nitpicky" mode, which reports all broken
      references. All remaining errors are references to flags without any
      documentation.
      
      Reviewers: austin, bgamari
      
      Reviewed By: bgamari
      
      Subscribers: rwbarton, thomie
      
      GHC Trac Issues: #13980
      
      Differential Revision: https://phabricator.haskell.org/D3778
      44b090be
  6. 26 Jun, 2017 1 commit
  7. 15 May, 2017 1 commit
  8. 25 Mar, 2016 1 commit