diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst
index 710765c6f1e..590fd6a4fa8 100644
--- a/doc/cabal-package-description-file.rst
+++ b/doc/cabal-package-description-file.rst
@@ -1451,6 +1451,8 @@ to have a way of finding out where a platform library got installed (other than
 searching the ``lib/`` directory). Instead, we install foreign libraries in
 ``~/.local/lib``.
 
+.. _build-info:
+
 Build information
 ^^^^^^^^^^^^^^^^^
 .. pkg-section:: None
@@ -1892,8 +1894,11 @@ system-dependent values for these fields.
 
 .. pkg-field:: ghc-options: token list
 
-    Additional options for GHC. You can often achieve the same effect
-    using the :pkg-field:`default-extensions` field, which is preferred.
+    Additional options for GHC.
+
+    If specifying extensions (via ``-X<Extension>`` flags) one can often achieve
+    the same effect using the :pkg-field:`default-extensions` field, which is
+    preferred.
 
     Options required only by one module may be specified by placing an
     ``OPTIONS_GHC`` pragma in the source file affected.
diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst
index c2f224cf421..9e955a0a096 100644
--- a/doc/cabal-project-description-file.rst
+++ b/doc/cabal-project-description-file.rst
@@ -785,20 +785,17 @@ ways a package option can be specified:
    apply to all packages, local ones from the project and also external
    dependencies.
 
-
 For example, the following options specify that :cfg-field:`optimization`
-should be turned off for all local packages, and that ``bytestring`` (possibly
-an external dependency) should be built with ``-fno-state-hack``::
+should be turned off for all local packages, and that ``awesome-package`` (possibly
+an external dependency) should have the flag ``some-flag`` disabled ::
 
     optimization: False
 
-    package bytestring
-        ghc-options: -fno-state-hack
+    package awesome-package
+        flags: -some-flag
 
-``ghc-options`` is not specifically described in this documentation, but is one
-of many fields for configuring programs.  They take the form
-``progname-options`` and ``progname-location``, and can be set for all local
-packages in a ``program-options`` stanza or under a package stanza.
+Note that options at the top level take precedence over those at the ``package``
+stanza for local packages.
 
 On the command line, these options are applied to all local packages.
 There is no per-package command line interface.
@@ -808,6 +805,26 @@ means that they are NOT supported by packages which use Custom setup
 scripts that require a version of the Cabal library older than when the
 feature was added.
 
+.. cfg-section:: package name or *
+
+    Specify package configuration options for the specific package (be it an
+    external or local package) or for all packages (external and local).
+
+    A ``package`` stanza can contain the configuration fields listed in this
+    section and ``<progname>-options``:
+
+    ::
+
+        package awesome-package
+          flags: -some-flag
+          profiling: True
+          cxx-options: -Wall
+
+    Program options are not extensively described in this documentation but a
+    good amount of them can be found in the :ref:`build-info` section.
+
+.. cfg-section:: None
+
 .. cfg-field:: flags: list of +flagname or -flagname (space separated)
                -f FLAGS or -fFLAGS, --flags=FLAGS
                --flags="+foo -bar", -ffoo, -f-bar
@@ -1639,11 +1656,36 @@ running ``setup haddock``.
     when complete. This will use ``xdg-open`` on Linux and BSD systems,
     ``open`` on macOS, and ``start`` on Windows.
 
+Program options
+^^^^^^^^^^^^^^^
+
+.. cfg-section:: program-options
+
+Program options can be specified once for all local packages by means of the
+``program-options`` stanza. For example:
+
+::
+
+    program-options
+        ghc-options: -Werror
+
+indicates that all **local packages** will provide ``-Werror`` to GHC when being
+built. On the other hand, the following snippet:
+
+::
+
+    package *
+        ghc-options: -Werror
+
+will apply ``-Werror`` to all packages, local and remote.
+
 Advanced global configuration options
 -------------------------------------
 
+.. cfg-section:: None
+
 .. cfg-field:: write-ghc-environment-files: always, never, or ghc8.4.4+
-               --write-ghc-environment-files=always\|never\|ghc8.4.4+
+               --write-ghc-environment-files=always|never|ghc8.4.4+
     :synopsis: Whether a ``.ghc.environment`` should be created after a successful build.
 
     :default: ``never``
diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index 2d318f8508f..9e16aefa6d6 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -548,7 +548,7 @@ class CabalPackageFieldXRef(CabalFieldXRef):
     '''
     section_key = 'cabal:pkg-section'
 
-class CabalConfigSection(CabalSection):
+class CabalConfigSection(CabalObject):
     """
     Marks section in package.cabal file
     """
@@ -556,6 +556,39 @@ class CabalConfigSection(CabalSection):
     section_key = 'cabal:cfg-section'
     target_prefix = 'cfg-section-'
 
+    def handle_signature(self, sig, signode):
+        '''
+        As in sphinx.directives.ObjectDescription
+
+        By default make an object description from name and adding
+        either deprecated or since as annotation.
+        '''
+        env = self.state.document.settings.env
+
+        sig = sig.strip()
+        parts = sig.split(' ',1)
+        name = parts[0]
+        signode += addnodes.desc_name(name, name)
+        signode += addnodes.desc_addname(' ', ' ')
+        if len(parts) > 1:
+            rest = parts[1].strip()
+            signode += addnodes.desc_annotation(rest, rest)
+
+        return name
+
+    def get_env_key(self, env, name):
+        store = CabalDomain.types[self.objtype]
+        return name, store
+
+    def run(self):
+        env = self.state.document.settings.env
+        section = self.arguments[0].strip().split(' ',1)[0]
+        if section == 'None':
+            env.ref_context.pop('cabal:cfg-section', None)
+            return []
+        env.ref_context['cabal:cfg-section'] = section
+        return super(CabalConfigSection, self).run()
+
 class ConfigField(CabalField):
     section_key = 'cabal:cfg-section'
     indextemplate = '%s ; cabal project option'
@@ -791,6 +824,9 @@ def make_full_name(typ, key, meta):
     if typ == 'pkg-section':
         return 'pkg-section-' + key
 
+    elif typ == 'cfg-section':
+        return 'cfg-section-' + key
+
     elif typ == 'pkg-field':
         section, name = key
         if section is not None:
@@ -914,4 +950,3 @@ class CabalLexer(lexer.RegexLexer):
 def setup(app):
     app.add_domain(CabalDomain)
     app.add_lexer('cabal', CabalLexer)
-