Commit cf8ab1ce authored by patrickdoc's avatar patrickdoc Committed by Ben Gamari

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
parent 6267d8c9
......@@ -104,7 +104,7 @@ _darcs/
/docs/index.html
/docs/users_guide/users_guide
/docs/users_guide/ghc.1
/docs/users_guide/*.gen.rst
/docs/users_guide/flags.pyc
/docs/users_guide/ghc_config.py
/docs/users_guide/ghc_config.pyc
/docs/users_guide/users_guide.pdf
......
......@@ -4338,6 +4338,7 @@ disableGlasgowExts :: DynP ()
disableGlasgowExts = do unSetGeneralFlag Opt_PrintExplicitForalls
mapM_ unSetExtensionFlag glasgowExtsFlags
-- Please keep what_glasgow_exts_does.rst up to date with this list
glasgowExtsFlags :: [LangExt.Extension]
glasgowExtsFlags = [
LangExt.ConstrainedClassMethods
......
......@@ -13,7 +13,7 @@ sys.path.insert(0, os.path.abspath('.'))
from ghc_config import extlinks, version
import ghc_config
extensions = ['sphinx.ext.extlinks', 'sphinx.ext.mathjax']
extensions = ['sphinx.ext.extlinks', 'sphinx.ext.mathjax', 'flags']
templates_path = ['.templates']
source_suffix = '.rst'
......@@ -32,7 +32,7 @@ pygments_style = 'tango'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['.build', "*.gen.rst"]
exclude_patterns = ['.build']
# -- Options for HTML output ---------------------------------------------
......@@ -72,6 +72,7 @@ latex_elements = {
\setsansfont{DejaVu Sans}
\setromanfont{DejaVu Serif}
\setmonofont{DejaVu Sans Mono}
\setlength{\\tymin}{45pt}
''',
}
......@@ -193,16 +194,6 @@ def setup(app):
objname='GHCi command',
indextemplate='pair: %s; GHCi command')
app.add_object_type('ghc-flag', 'ghc-flag',
objname='GHC command-line option',
parse_node=parse_flag,
indextemplate='pair: %s; GHC option',
doc_field_types=[
Field('since', label='Introduced in GHC version', names=['since']),
Field('default', label='Default value', names=['default']),
Field('static')
])
# Haddock references
app.add_role('th-ref', haddock_role('template-haskell'))
app.add_role('base-ref', haddock_role('base'))
......
......@@ -7,6 +7,11 @@ useable by most UNIX debugging tools.
.. ghc-flag:: -g
-g⟨n⟩
:shortdesc: Produce DWARF debug information in compiled object files.
⟨n⟩ can be 0, 1, or 2, with higher numbers producing richer
output. If ⟨n⟩ is omitted level 2 is assumed.
:type: dynamic
:category: debugging
:since: 7.10, numeric levels since 8.0
......
This diff is collapsed.
......@@ -347,11 +347,29 @@ Will be rendered as,
Sets the context switch interval to ⟨s⟩ seconds.
and will have an associated index entry generated automatically. Note that, as
in Style Conventions below, we use ``⟨⟩`` instead of less-than/greater-than
signs. To reference a ``ghc-flag`` or ``rts-flag``, you must match the
definition exactly, including the arguments. A quick way to find the exact
names and special characters is,
and will have an associated index entry generated automatically.
The ``ghc-flag`` directive requires a few extra parameters to be passed.
This extra information is used to generate the :ref:`flag-reference` and the
man page. A ``ghc-flag`` directive looks like this,
.. code-block:: rest
.. ghc-flag:: -fasm
:shortdesc: Use the native code generator
:type: dynamic
:reverse: -fllvm
:category: codegen
Regular description...
When rendered, the extra parameters will be hidden, and the data stored for
later use. For more details, see the Sphinx extension ``flags.py``.
Note that, as in Style Conventions below, we use ``⟨⟩`` instead of
less-than/greater-than signs. To reference a ``ghc-flag`` or ``rts-flag``, you
must match the definition exactly, including the arguments. A quick way to find
the exact names and special characters is,
.. code-block:: sh
......
......@@ -196,13 +196,22 @@ module in a registered package that exports a plugin. Arguments can be given to
plugins with the :ghc-flag:`-fplugin-opt=module:args` option.
.. ghc-flag:: -fplugin=module
:shortdesc: Load a plugin exported by a given module
:type: dynamic
:category: plugins
Load the plugin in the given module. The module must be a member of a
package registered in GHC's package database.
.. ghc-flag:: -fplugin-opt=⟨module⟩:⟨args⟩
:shortdesc: Give arguments to a plugin module; module must be specified with
:ghc-flag:`-fplugin=⟨module⟩`
:type: dynamic
:category: plugins
Give arguments to a plugin module; module must be specified with
:ghc-flag:`-fplugin=⟨module⟩`.
Pass arguments ⟨args⟩ to the given plugin.
As an example, in order to load the plugin exported by ``Foo.Plugin`` in
the package ``foo-ghc-plugin``, and give it the parameter "baz", we
......@@ -227,6 +236,9 @@ the same; however, there are a few command line options which
control specifically plugin packages:
.. ghc-flag:: -plugin-package ⟨pkg⟩
:shortdesc: Expose ⟨pkg⟩ for plugins
:type: dynamic
:category: plugins
This option causes the installed package ⟨pkg⟩ to be exposed for plugins,
such as :ghc-flag:`-fplugin=⟨module⟩`. The package ⟨pkg⟩ can be specified
......@@ -241,6 +253,9 @@ control specifically plugin packages:
to be linked into the resulting executable or shared object.
.. ghc-flag:: -plugin-package-id ⟨pkg-id⟩
:shortdesc: Expose ⟨pkg-id⟩ for plugins
:type: dynamic
:category: plugins
Exposes a package in the plugin namespace like :ghc-flag:`-plugin-package
⟨pkg⟩`, but the package is named by its installed package ID rather than by
......@@ -251,6 +266,9 @@ control specifically plugin packages:
described in :ref:`package-thinning-and-renaming`.
.. ghc-flag:: -hide-all-plugin-packages
:shortdesc: Hide all packages for plugins by default
:type: dynamic
:category: plugins
By default, all exposed packages in the normal, source import namespace are
also available for plugins. This causes those packages to be hidden by
......
......@@ -8,6 +8,12 @@ Foreign function interface (FFI)
single: interfacing with native code
.. ghc-flag:: -XForeignFunctionInterface
:shortdesc: Enable :ref:`foreign function interface <ffi>`.
:type: dynamic
:reverse: -XNoForeignFunctionInterface
:category: language
:since: 6.8.1
Allow use of the Haskell foreign function interface.
......@@ -118,6 +124,14 @@ come with GHC. For more details see the
Interruptible foreign calls
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. ghc-flag:: -XInterruptibleFFI
:shortdesc: Enable interruptible FFI.
:type: dynamic
:reverse: -XNoInterruptibleFFI
:category: language
:since: 7.2.1
This concerns the interaction of foreign calls with
``Control.Concurrent.throwTo``. Normally when the target of a
``throwTo`` is involved in a foreign call, the exception is not raised
......@@ -167,6 +181,14 @@ it is not typically necessary to handle ``ERROR_OPERATION_ABORTED``.
The CAPI calling convention
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. ghc-flag:: -XCApiFFI
:shortdesc: Enable :ref:`the CAPI calling convention <ffi-capi>`.
:type: dynamic
:reverse: -XNoCAPIFFI
:category: language
:since: 7.10.1
The ``CApiFFI`` extension allows a calling convention of ``capi`` to be
used in foreign declarations, e.g. ::
......
This diff is collapsed.
This diff is collapsed.
......@@ -11,9 +11,7 @@
# -----------------------------------------------------------------------------
docs/users_guide_RST_SOURCES := \
$(utils/mkUserGuidePart_GENERATED_RST_SOURCES) \
$(wildcard docs/users_guide/*.rst)
docs/users_guide_RST_SOURCES := $(wildcard docs/users_guide/*.rst)
$(eval $(call sphinx,docs/users_guide,users_guide))
......@@ -26,7 +24,7 @@ MAN_SECTION := 1
MAN_PAGES := docs/users_guide/build-man/ghc.1
ifneq "$(BINDIST)" "YES"
$(MAN_PAGES): $(docs/users_guide_MAN_RST_SOURCES) $(utils/mkUserGuidePart_GENERATED_RST_SOURCES)
$(MAN_PAGES): $(docs/users_guide_MAN_RST_SOURCES)
$(SPHINXBUILD) -b man -d docs/users_guide/.doctrees-man docs/users_guide docs/users_guide/build-man
endif
......
......@@ -62,7 +62,317 @@ Common suffixes of file names for Haskell are:
Options
-------
.. include:: all-flags.gen.rst
.. flag-print::
:type: summary
:category: codegen
.. flag-print::
:type: summary
:category: debugging
.. flag-print::
:type: summary
:category: cpp
.. flag-print::
:type: summary
:category: search-path
.. flag-print::
:type: summary
:category: interactive
.. flag-print::
:type: summary
:category: interface-files
.. flag-print::
:type: summary
:category: keep-intermediates
.. flag-print::
:type: summary
:category: language
.. flag-print::
:type: summary
:category: linking
.. flag-print::
:type: summary
:category: misc
.. flag-print::
:type: summary
:category: modes
.. flag-print::
:type: summary
:category: optimization
.. flag-print::
:type: summary
:category: optimization-levels
.. flag-print::
:type: summary
:category: packages
.. flag-print::
:type: summary
:category: phases
.. flag-print::
:type: summary
:category: phase-programs
.. flag-print::
:type: summary
:category: phase-options
.. flag-print::
:type: summary
:category: platform-options
.. flag-print::
:type: summary
:category: plugins
.. flag-print::
:type: summary
:category: profiling
.. flag-print::
:type: summary
:category: coverage
.. flag-print::
:type: summary
:category: recompilation
.. flag-print::
:type: summary
:category: redirect-output
.. flag-print::
:type: summary
:category: temp-files
.. flag-print::
:type: summary
:category: verbosity
.. flag-print::
:type: summary
:category: warnings
Code generation
~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: codegen
Debugging the compiler
~~~~~~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: debugging
C pre-processor
~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: cpp
Finding imports
~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: search-path
Interactive mode
~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: interactive
Interface files
~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: interface-files
Keeping intermediate files
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: keep-intermediates
Language options
~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: language
Linking options
~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: linking
Miscellaneous options
~~~~~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: misc
Modes of operation
~~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: modes
Individual optimizations
~~~~~~~~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: optimization
Optimization levels
~~~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: optimization-levels
Package options
~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: packages
Phases of compilation
~~~~~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: phases
Overriding external programs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: phase-programs
Phase-specific options
~~~~~~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: phase-options
Platform-specific options
~~~~~~~~~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: platform-options
Compiler plugins
~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: plugins
Profiling
~~~~~~~~~
.. flag-print::
:type: list
:category: profiling
Program coverage
~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: coverage
Recompilation checking
~~~~~~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: recompilation
Redirecting output
~~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: redirect-output
Temporary files
~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: temp-files
Verbosity options
~~~~~~~~~~~~~~~~~
.. flag-print::
:type: list
:category: verbosity
Warnings
~~~~~~~~
.. flag-print::
:type: list
:category: warnings
Copyright
---------
......
......@@ -434,6 +434,10 @@ The statement ``x <- return 42`` means “execute ``return 42`` in the
future statements, for example to print it as we did above.
.. ghc-flag:: -fprint-bind-result
:shortdesc: :ref:`Turn on printing of binding results in GHCi <ghci-stmts>`
:type: dynamic
:reverse: -fno-print-bind-result
:category:
If :ghc-flag:`-fprint-bind-result` is set then GHCi will print the result of a
statement if and only if:
......@@ -1020,6 +1024,14 @@ Type defaulting in GHCi
single: Show class
.. ghc-flag:: -XExtendedDefaultRules
:shortdesc: Use GHCi's
:ref:`extended default rules <extended-default-rules>` in a normal
module.
:type: dynamic
:reverse: -XNoExtendedDefaultRules
:category: language
:since: 6.8.1
Allow defaulting to take place for more than just numeric classes.
......@@ -1155,6 +1167,10 @@ it survive a :ghci-cmd:`:cd`, :ghci-cmd:`:add`, :ghci-cmd:`:load`,
:ghci-cmd:`:reload` or, :ghci-cmd:`:set`.
.. ghc-flag:: -interactive-print ⟨expr⟩
:shortdesc: :ref:`Select the function to use for printing evaluated
expressions in GHCi <ghci-interactive-print>`
:type: dynamic
:category:
Set the function used by GHCi to print evaluation results. Expression
must be of type ``C a => a -> IO ()``.
......@@ -1744,6 +1760,10 @@ is we found that logging each breakpoint in the history cuts performance
by a factor of 2 or more.
.. ghc-flag:: -fghci-hist-size=⟨n⟩
:shortdesc: Set the number of entries GHCi keeps for ``:history``.
See :ref:`ghci-debugger`.
:type: dynamic
:category:
:default: 50
......@@ -1808,12 +1828,26 @@ program was doing when it was in an infinite loop. Just hit Control-C,
and examine the history to find out what was going on.
.. ghc-flag:: -fbreak-on-exception
-fbreak-on-error
:shortdesc: :ref:`Break on any exception thrown <ghci-debugger-exceptions>`
:type: dynamic
:reverse: -fno-break-on-exception
:category:
Causes GHCi to halt evaluation and return to the interactive prompt
in the event of an exception. While :ghc-flag:`-fbreak-on-exception` breaks
on all exceptions, :ghc-flag:`-fbreak-on-error` breaks on only those which
would otherwise be uncaught.
in the event of an exception. :ghc-flag:`-fbreak-on-exception` breaks
on all exceptions.
.. ghc-flag:: -fbreak-on-error
:shortdesc: :ref:`Break on uncaught exceptions and errors
<ghci-debugger-exceptions>`
:type: dynamic
:reverse: -fno-break-on-error
:category:
Causes GHCi to halt evaluation and return to the interactive prompt in the
event of an exception. :ghc-flag:`-fbreak-on-error` breaks on only those
exceptions which would otherwise be uncaught.
Example: inspecting functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -1954,15 +1988,20 @@ also make sense in interactive mode. The ones that don't make sense are
mostly obvious.
.. ghc-flag:: -flocal-ghci-history
:shortdesc: Use current directory for the GHCi command history
file ``.ghci-history``.
:type: dynamic
:reverse: -fno-local-ghci-history
:category:
By default, GHCi keeps global history in ``~/.ghc/ghci_history`` or
``%APPDATA%/<app>/ghci_history``, but you can use current directory, e.g.:
By default, GHCi keeps global history in ``~/.ghc/ghci_history`` or
``%APPDATA%/<app>/ghci_history``, but you can use current directory, e.g.:
.. code-block:: none
.. code-block:: none
$ ghci -flocal-ghci-history
$ ghci -flocal-ghci-history
It will create ``.ghci-history`` in current folder where GHCi is launched.
It will create ``.ghci-history`` in current folder where GHCi is launched.
Packages
~~~~~~~~
......@@ -3063,11 +3102,17 @@ Two command-line options control whether the startup files files are
read:
.. ghc-flag:: -ignore-dot-ghci
:shortdesc: Disable reading of ``.ghci`` files
:type: dynamic
:category:
Don't read either :file:`./.ghci` or the other startup files when
starting up.
.. ghc-flag:: -ghci-script
:shortdesc: Read additional ``.ghci`` files
:type: dynamic
:category:
Read a specific file after the usual startup files. Maybe be
specified repeatedly for multiple inputs.
......@@ -3156,6 +3201,9 @@ separate process for running interpreted code, and communicate with it
using messages over a pipe.
.. ghc-flag:: -fexternal-interpreter
:shortdesc: Run interpreted code in a separate process
:type: dynamic
:category: misc
:since: 8.0.1
......
This diff is collapsed.
......@@ -128,6 +128,9 @@ command (see :ref:`package-management`):
The GHC command line options that control packages are:
.. ghc-flag:: -package pkg
:shortdesc: Expose package pkg
:type: dynamic/ ``:set``
:category:
This option causes the installed package pkg to be exposed. The
package pkg can be specified in full with its version number (e.g.
......@@ -177,6 +180,9 @@ The GHC command line options that control packages are:
$ ghc -o myprog Foo.hs Main.hs -package network
.. ghc-flag:: -package-id ⟨unit-id⟩
:shortdesc: Expose package by id ⟨unit-id⟩
:type: dynamic/ ``:set``
:category:
Exposes a package like :ghc-flag:`-package ⟨pkg⟩`, but the package is named
by its unit ID (i.e. the value of ``id`` in its entry in the installed
......@@ -187,6 +193,9 @@ The GHC command line options that control packages are:
renaming described in :ref:`package-thinning-and-renaming`.
.. ghc-flag:: -hide-all-packages
:shortdesc: Hide all packages by default
:type: dynamic
:category:
Ignore the exposed flag on installed packages, and hide them all by
default. If you use this flag, then any packages you require
......@@ -199,6 +208,9 @@ The GHC command line options that control packages are:
``-hide-all-packages`` flag to GHC, for exactly this reason.
.. ghc-flag:: -hide-package ⟨pkg⟩
:shortdesc: Hide package ⟨pkg⟩
:type: dynamic/ ``:set``
:category:
This option does the opposite of :ghc-flag:`-package ⟨pkg⟩`: it causes the
specified package to be hidden, which means that none of its modules
......@@ -209,6 +221,9 @@ The GHC command line options that control packages are:
exposed package.
.. ghc-flag:: -ignore-package ⟨pkg⟩
:shortdesc: Ignore package ⟨pkg⟩
:type: dynamic/ ``:set``
:category:
Causes the compiler to behave as if package ⟨pkg⟩, and any packages
that depend on ⟨pkg⟩, are not installed at all.
......@@ -220,11 +235,18 @@ The GHC command line options that control packages are:
:ghc-flag:`-ignore-package pkg` flag can be useful.
.. ghc-flag:: -no-auto-link-packages
:shortdesc: Don't automatically link in the base and rts packages.
:type: dynamic
:category:
By default, GHC will automatically link in the ``base`` and ``rts``
packages. This flag disables that behaviour.
.. ghc-flag:: -this-unit-id ⟨unit-id⟩
:shortdesc: Compile to be part of unit (i.e. package)
⟨unit-id⟩
:type: dynamic
:category:
Tells GHC that the module being compiled forms part of unit ID
⟨unit-id⟩; internally, these keys are used to determine type equality
......@@ -234,6 +256,10 @@ The GHC command line options that control packages are:
way in later releases.
.. ghc-flag:: -trust ⟨pkg⟩
:shortdesc: Expose package ⟨pkg⟩ and set it to be trusted
:type: dynamic/ ``:set``
:category: