Rewrite usage/configuration.rst (#12537)

- Remove now-removed configuration values
- Use obvious 'unset' defaults for ``project`` and ``author``
- Prefer 'e.g.' to 'ex.'
- Allow non-list sequence types in various configuration values
- Add types and defaults to every confval directive

Author: AA-Turner

CHANGES.rst

@@ -60,6 +60,14 @@ Features added
   Patch by Tim Hoffmann.
 * #12536: Add the :rst:dir:`confval` directive.
   Patch by Adam Turner.
+* #12537: :confval:`c_id_attributes`, :confval:`c_paren_attributes`,
+  :confval:`cpp_id_attributes`, and :confval:`cpp_paren_attributes`
+  can now be a tuple of strings.
+  :confval:`c_extra_keywords`, :confval:`gettext_additional_targets`,
+  :confval:`html_domain_indices`, :confval:`latex_domain_indices`,
+  and :confval:`texinfo_domain_indices`,
+  can now be a set of strings.
+  Patch by Adam Turner.
 
 Bugs fixed
 ----------
@@ -78,9 +86,8 @@ Bugs fixed
 * #12380: LaTeX: Footnote mark sometimes indicates ``Page N`` where ``N`` is
   the current page number and the footnote does appear on that same page.
   Patch by Jean-François B.
-* #12416: :confval:`root_doc` is synchronized with :confval:`master_doc`
-  so that if either of the two values is modified, the other reflects that
-  modification. It is still recommended to use :confval:`root_doc`.
+* #12416: Ensure that configuration setting aliases are always synchronised
+  when one value or the other is modified.
   Patch by Bénédikt Tran.
 * #12220: Fix loading custom template translations for ``en`` locale.
   Patch by Nicolas Peugnet.
@@ -3828,7 +3835,7 @@ Deprecated
 * The arguments of ``Epub3Builder.build_navigation_doc()``
 * The config variables
 
-  - :confval:`html_experimental_html5_writer`
+  - :confval:`!html_experimental_html5_writer`
 
 * The ``encoding`` argument of ``autodoc.Documenter.get_doc()``,
   ``autodoc.DocstringSignatureMixin.get_doc()``,
@@ -3944,7 +3951,7 @@ Features added
 * #4611: epub: Show warning for duplicated ToC entries
 * #1851: Allow to omit an argument for :rst:dir:`code-block` directive.  If
   omitted, it follows :rst:dir:`highlight` or :confval:`highlight_language`
-* #4587: html: Add :confval:`html4_writer` to use old HTML4 writer
+* #4587: html: Add :confval:`!html4_writer` to use old HTML4 writer
 * #6016: HTML search: A placeholder for the search summary prevents search
   result links from changing their position when the search terminates.  This
   makes navigating search results easier.
@@ -4264,7 +4271,7 @@ Deprecated
 
 1.8.0b1
 
-* :confval:`source_parsers` is deprecated
+* :confval:`!source_parsers` is deprecated
 * :confval:`autodoc_default_flags` is deprecated
 * quickstart: ``--epub`` option becomes default, so it is deprecated
 * Drop function based directive support.  For now, Sphinx only supports class
@@ -6404,7 +6411,7 @@ Features added
 --------------
 
 * #1873, #1876, #2278: Add ``page_source_suffix`` html context variable. This
-  should be introduced with :confval:`source_parsers` feature. Thanks for Eric
+  should be introduced with :confval:`!source_parsers` feature. Thanks for Eric
   Holscher.
 
 
@@ -6471,7 +6478,7 @@ Bugs fixed
 * #2186: Fix LaTeX output of \mathbb in math
 * #1480, #2188: LaTeX: Support math in section titles
 * #2071: Fix same footnote in more than two section titles => LaTeX/PDF Bug
-* #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains non-ascii
+* #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains non-ASCII
   characters
 * #2193: Fix shutil.SameFileError if source directory and destination directory
   are same
@@ -6646,7 +6653,7 @@ Features added
 * The :confval:`source_suffix` config value can now be a list of multiple
   suffixes.
 * Add the ability to specify source parsers by source suffix with the
-  :confval:`source_parsers` config value.
+  :confval:`!source_parsers` config value.
 * #1675: A new builder, AppleHelpBuilder, has been added that builds Apple
   Help Books.