Use long options to sphinx-build in our documentation

Author: AA-Turner

doc/development/howtos/builders.rst

@@ -13,7 +13,7 @@ value.
 Builder extensions should define an entry point in the ``"sphinx.builders"``
 group. The name of the entry point needs to match your builder's
 :attr:`~.Builder.name` attribute, which is the name passed to the
-:option:`sphinx-build -b` option. The entry point value should equal the
+:option:`sphinx-build --builder` option. The entry point value should equal the
 dotted name of the extension module. Here is an example of how an entry point
 for 'mybuilder' can be defined in the extension's ``pyproject.toml``
 

doc/man/sphinx-build.rst

@@ -43,7 +43,7 @@ Options
       the source and output directories, before any other options are passed.
       For example::
 
-          sphinx-build -M html ./source ./build -W --keep-going
+          sphinx-build -M html ./source ./build --fail-on-warning --keep-going
 
    The *make-mode* provides the same build functionality as
    a default :ref:`Makefile or Make.bat <makefile_options>`,
@@ -261,8 +261,10 @@ Options
 
 .. option:: --keep-going
 
-   With -W option, keep going processing when getting warnings to the end
-   of build, and ``sphinx-build`` exits with exit status 1.
+   Only applicable whilst using :option:`--fail-on-warning`,
+   which by default exits :program:`sphinx-build` on the first warning.
+   Using :option:`!--keep-going` runs :program:`!sphinx-build` to completion
+   and exits with exit status 1 if errors are encountered.
 
    .. versionadded:: 1.8
 

doc/usage/extensions/autodoc.rst

@@ -765,8 +765,8 @@ There are also config values that you can set:
 
 .. confval:: autodoc_warningiserror
 
-   This value controls the behavior of :option:`sphinx-build -W` during
-   importing modules.
+   This value controls the behavior of :option:`sphinx-build --fail-on-warning`
+   during importing modules.
    If ``False`` is given, autodoc forcedly suppresses the error if the imported
    module emits warnings.  By default, ``True``.