Issue #26638: Mask undefined CLI options to defeat new Sphinx warnings

Doc/install/index.rst

@@ -201,7 +201,7 @@ As implied above, the :command:`build` command is responsible for putting the
 files to install into a *build directory*.  By default, this is :file:`build`
 under the distribution root; if you're excessively concerned with speed, or want
 to keep the source tree pristine, you can change the build directory with the
-:option:`--build-base` option. For example::
+:option:`!--build-base` option. For example::
 
    python setup.py build --build-base=/path/to/pybuild/foo-1.0
 
@@ -399,7 +399,7 @@ Installing a new module distribution is as simple as ::
 
    python setup.py install --home=<dir>
 
-where you can supply any directory you like for the :option:`--home` option.  On
+where you can supply any directory you like for the :option:`!--home` option.  On
 Unix, lazy typists can just type a tilde (``~``); the :command:`install` command
 will expand this to your home directory::
 
@@ -410,7 +410,7 @@ to :ref:`modify Python's search path <inst-search-path>` or edit
 :mod:`sitecustomize` (see :mod:`site`) to call :func:`site.addsitedir` or edit
 :data:`sys.path`.
 
-The :option:`--home` option defines the installation base directory.  Files are
+The :option:`!--home` option defines the installation base directory.  Files are
 installed to the following directories under the installation base as follows:
 
 =============== ===========================================================
@@ -455,12 +455,12 @@ be done with ::
 
    /usr/local/bin/python setup.py install --prefix=/mnt/@server/export
 
-In either case, the :option:`--prefix` option defines the installation base, and
-the :option:`--exec-prefix` option defines the platform-specific installation
+In either case, the :option:`!--prefix` option defines the installation base, and
+the :option:`!--exec-prefix` option defines the platform-specific installation
 base, which is used for platform-specific files.  (Currently, this just means
 non-pure module distributions, but could be expanded to C libraries, binary
-executables, etc.)  If :option:`--exec-prefix` is not supplied, it defaults to
-:option:`--prefix`.  Files are installed as follows:
+executables, etc.)  If :option:`!--exec-prefix` is not supplied, it defaults to
+:option:`!--prefix`.  Files are installed as follows:
 
 ================= ==========================================================
 Type of file      Installation directory
@@ -472,13 +472,13 @@ data              :file:`{prefix}`
 C headers         :file:`{prefix}/include/python{X.Y}{abiflags}/{distname}`
 ================= ==========================================================
 
-There is no requirement that :option:`--prefix` or :option:`--exec-prefix`
+There is no requirement that :option:`!--prefix` or :option:`!--exec-prefix`
 actually point to an alternate Python installation; if the directories listed
 above do not already exist, they are created at installation time.
 
 Incidentally, the real reason the prefix scheme is important is simply that a
-standard Unix installation uses the prefix scheme, but with :option:`--prefix`
-and :option:`--exec-prefix` supplied by Python itself as ``sys.prefix`` and
+standard Unix installation uses the prefix scheme, but with :option:`!--prefix`
+and :option:`!--exec-prefix` supplied by Python itself as ``sys.prefix`` and
 ``sys.exec_prefix``.  Thus, you might think you'll never use the prefix scheme,
 but every time you run ``python setup.py install`` without any other options,
 you're using it.
@@ -491,7 +491,7 @@ responsibility to ensure that the interpreter used to run extensions installed
 in this way is compatible with the interpreter used to build them.  The best way
 to do this is to ensure that the two interpreters are the same version of Python
 (possibly different builds, or possibly copies of the same build).  (Of course,
-if your :option:`--prefix` and :option:`--exec-prefix` don't even point to an
+if your :option:`!--prefix` and :option:`!--exec-prefix` don't even point to an
 alternate Python installation, this is immaterial.)
 
 
@@ -501,7 +501,7 @@ Alternate installation: Windows (the prefix scheme)
 ---------------------------------------------------
 
 Windows has no concept of a user's home directory, and since the standard Python
-installation under Windows is simpler than under Unix, the :option:`--prefix`
+installation under Windows is simpler than under Unix, the :option:`!--prefix`
 option has traditionally been used to install additional packages in separate
 locations on Windows. ::
 
@@ -509,8 +509,8 @@ locations on Windows. ::
 
 to install modules to the :file:`\\Temp\\Python` directory on the current drive.
 
-The installation base is defined by the :option:`--prefix` option; the
-:option:`--exec-prefix` option is not supported under Windows, which means that
+The installation base is defined by the :option:`!--prefix` option; the
+:option:`!--exec-prefix` option is not supported under Windows, which means that
 pure Python modules and extension modules are installed into the same location.
 Files are installed as follows:
 
@@ -562,7 +562,7 @@ difference between Python and extension modules.)
 For example, say you're installing a module distribution to your home directory
 under Unix---but you want scripts to go in :file:`~/scripts` rather than
 :file:`~/bin`. As you might expect, you can override this directory with the
-:option:`--install-scripts` option; in this case, it makes most sense to supply
+:option:`!--install-scripts` option; in this case, it makes most sense to supply
 a relative path, which will be interpreted relative to the installation base
 directory (your home directory, in this case)::
 
@@ -572,7 +572,7 @@ Another Unix example: suppose your Python installation was built and installed
 with a prefix of :file:`/usr/local/python`, so under a standard  installation
 scripts will wind up in :file:`/usr/local/python/bin`.  If you want them in
 :file:`/usr/local/bin` instead, you would supply this absolute directory for the
-:option:`--install-scripts` option::
+:option:`!--install-scripts` option::
 
    python setup.py install --install-scripts=/usr/local/bin
 
@@ -932,10 +932,10 @@ Let's examine each of the fields in turn.
   to be in Objective C.
 
 * *cpparg* is an argument for the C preprocessor,  and is anything starting with
-  :option:`!-I`, :option:`-D`, :option:`!-U` or :option:`-C`.
+  :option:`!-I`, :option:`!-D`, :option:`!-U` or :option:`!-C`.
 
-* *library* is anything ending in :file:`.a` or beginning with :option:`-l` or
-  :option:`-L`.
+* *library* is anything ending in :file:`.a` or beginning with :option:`!-l` or
+  :option:`!-L`.
 
 If a particular platform requires a special library on your platform, you can
 add it by editing the :file:`Setup` file and running ``python setup.py build``.
@@ -944,20 +944,20 @@ For example, if the module defined by the line ::
    foo foomodule.c
 
 must be linked with the math library :file:`libm.a` on your platform, simply add
-:option:`-lm` to the line::
+:option:`!-lm` to the line::
 
    foo foomodule.c -lm
 
 Arbitrary switches intended for the compiler or the linker can be supplied with
-the :option:`-Xcompiler` *arg* and :option:`-Xlinker` *arg* options::
+the :option:`!-Xcompiler` *arg* and :option:`!-Xlinker` *arg* options::
 
    foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
 
-The next option after :option:`-Xcompiler` and :option:`-Xlinker` will be
+The next option after :option:`!-Xcompiler` and :option:`!-Xlinker` will be
 appended to the proper command line, so in the above example the compiler will
-be passed the :option:`-o32` option, and the linker will be passed
-:option:`-shared`.  If a compiler option requires an argument, you'll have to
-supply multiple :option:`-Xcompiler` options; for example, to pass ``-x c++``
+be passed the :option:`!-o32` option, and the linker will be passed
+:option:`!-shared`.  If a compiler option requires an argument, you'll have to
+supply multiple :option:`!-Xcompiler` options; for example, to pass ``-x c++``
 the :file:`Setup` file would have to contain ``-Xcompiler -x -Xcompiler c++``.
 
 Compiler flags can also be supplied through setting the :envvar:`CFLAGS`