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

Author: vadmium

Doc/distutils/apiref.rst

@@ -205,7 +205,7 @@ the full reference.
    |                        | to or ``None`` to define it    |                           |
    |                        | without a particular value     |                           |
    |                        | (equivalent of ``#define FOO`` |                           |
-   |                        | in source or :option:`-DFOO`   |                           |
+   |                        | in source or :option:`!-DFOO`  |                           |
    |                        | on Unix C compiler command     |                           |
    |                        | line)                          |                           |
    +------------------------+--------------------------------+---------------------------+
@@ -319,11 +319,11 @@ This module provides the following functions.
 
 .. function:: gen_preprocess_options(macros, include_dirs)
 
-   Generate C pre-processor options (:option:`-D`, :option:`!-U`, :option:`!-I`) as
+   Generate C pre-processor options (:option:`!-D`, :option:`!-U`, :option:`!-I`) as
    used by at least two types of compilers: the typical Unix compiler and Visual
    C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
    means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define
-   (:option:`-D`) macro *name* to *value*.  *include_dirs* is just a list of
+   (:option:`!-D`) macro *name* to *value*.  *include_dirs* is just a list of
    directory names to be added to the header file search path (:option:`!-I`).
    Returns a list of command-line options suitable for either Unix compilers or
    Visual C++.
@@ -359,7 +359,7 @@ This module provides the following functions.
 
 .. function:: show_compilers()
 
-   Print list of available compilers (used by the :option:`--help-compiler` options
+   Print list of available compilers (used by the :option:`!--help-compiler` options
    to :command:`build`, :command:`build_ext`, :command:`build_clib`).
 
 
@@ -789,23 +789,23 @@ This module provides the following functions.
 This module provides the :class:`UnixCCompiler` class, a subclass of
 :class:`CCompiler` that handles the typical Unix-style command-line  C compiler:
 
-* macros defined with :option:`-Dname[=value]`
+* macros defined with :option:`!-Dname[=value]`
 
-* macros undefined with :option:`-Uname`
+* macros undefined with :option:`!-Uname`
 
-* include search directories specified with :option:`-Idir`
+* include search directories specified with :option:`!-Idir`
 
-* libraries specified with :option:`-llib`
+* libraries specified with :option:`!-llib`
 
-* library search directories specified with :option:`-Ldir`
+* library search directories specified with :option:`!-Ldir`
 
 * compile handled by :program:`cc` (or similar) executable with :option:`!-c`
   option: compiles :file:`.c` to :file:`.o`
 
 * link static library handled by :program:`ar` command (possibly with
   :program:`ranlib`)
 
-* link shared library handled by :program:`cc` :option:`-shared`
+* link shared library handled by :program:`cc` :option:`!-shared`
 
 
 :mod:`distutils.msvccompiler` --- Microsoft Compiler
@@ -1318,8 +1318,8 @@ provides the following additional features:
 
 * options set attributes of a passed-in object
 
-* boolean options can have "negative aliases" --- eg. if :option:`--quiet` is
-  the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
+* boolean options can have "negative aliases" --- eg. if :option:`!--quiet` is
+  the "negative alias" of :option:`!--verbose`, then :option:`!--quiet` on the
   command line sets *verbose* to false.
 
 .. function:: fancy_getopt(options, negative_opt, object, args)

Doc/distutils/builtdist.rst

@@ -57,7 +57,7 @@ built distributions, such as an RPM package or an executable installer for
 Windows, is far more convenient for users even if your distribution doesn't
 include any extensions.
 
-The :command:`bdist` command has a :option:`--formats` option, similar to the
+The :command:`bdist` command has a :option:`!--formats` option, similar to the
 :command:`sdist` command, which you can use to select the types of built
 distribution to generate: for example, ::
 
@@ -123,7 +123,7 @@ Notes:
    requires external :program:`rpm` utility, version 3.0.4 or better (use ``rpm
    --version`` to find out which version you have)
 
-You don't have to use the :command:`bdist` command with the :option:`--formats`
+You don't have to use the :command:`bdist` command with the :option:`!--formats`
 option; you can also use the command that directly implements the format you're
 interested in.  Some of these :command:`bdist` "sub-commands" actually generate
 several similar formats; for instance, the :command:`bdist_dumb` command
@@ -174,7 +174,7 @@ The usual way to create an RPM of your module distribution is to run the
 
    python setup.py bdist_rpm
 
-or the :command:`bdist` command with the :option:`--format` option::
+or the :command:`bdist` command with the :option:`!--format` option::
 
    python setup.py bdist --formats=rpm
 
@@ -249,7 +249,7 @@ configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`.  If
 you distribute or package many Python module distributions, you might want to
 put options that apply to all of them in your personal Distutils configuration
 file (:file:`~/.pydistutils.cfg`).  If you want to temporarily disable
-this file, you can pass the :option:`--no-user-cfg` option to :file:`setup.py`.
+this file, you can pass the :option:`!--no-user-cfg` option to :file:`setup.py`.
 
 There are three steps to building a binary RPM package, all of which are
 handled automatically by the Distutils:
@@ -267,10 +267,10 @@ Normally, RPM bundles the last two steps together; when you use the Distutils,
 all three steps are typically bundled together.
 
 If you wish, you can separate these three steps.  You can use the
-:option:`--spec-only` option to make :command:`bdist_rpm` just create the
+:option:`!--spec-only` option to make :command:`bdist_rpm` just create the
 :file:`.spec` file and exit; in this case, the :file:`.spec` file will be
 written to the "distribution directory"---normally :file:`dist/`, but
-customizable with the :option:`--dist-dir` option.  (Normally, the :file:`.spec`
+customizable with the :option:`!--dist-dir` option.  (Normally, the :file:`.spec`
 file winds up deep in the "build tree," in a temporary directory created by
 :command:`bdist_rpm`.)
 
@@ -307,7 +307,7 @@ is usually as easy as running::
 
    python setup.py bdist_wininst
 
-or the :command:`bdist` command with the :option:`--formats` option::
+or the :command:`bdist` command with the :option:`!--formats` option::
 
    python setup.py bdist --formats=wininst
 
@@ -325,20 +325,20 @@ support.
 The installer will try to compile pure modules into :term:`bytecode` after installation
 on the target system in normal and optimizing mode.  If you don't want this to
 happen for some reason, you can run the :command:`bdist_wininst` command with
-the :option:`--no-target-compile` and/or the :option:`--no-target-optimize`
+the :option:`!--no-target-compile` and/or the :option:`!--no-target-optimize`
 option.
 
 By default the installer will display the cool "Python Powered" logo when it is
 run, but you can also supply your own 152x261 bitmap which must be a Windows
-:file:`.bmp` file with the :option:`--bitmap` option.
+:file:`.bmp` file with the :option:`!--bitmap` option.
 
 The installer will also display a large title on the desktop background window
 when it is run, which is constructed from the name of your distribution and the
 version number.  This can be changed to another text by using the
-:option:`--title` option.
+:option:`!--title` option.
 
 The installer file will be written to the "distribution directory" --- normally
-:file:`dist/`, but customizable with the :option:`--dist-dir` option.
+:file:`dist/`, but customizable with the :option:`!--dist-dir` option.
 
 .. _cross-compile-windows:
 
@@ -350,7 +350,7 @@ Windows platforms.  In practice, this means that with the correct tools
 installed, you can use a 32bit version of Windows to create 64bit extensions
 and vice-versa.
 
-To build for an alternate platform, specify the :option:`--plat-name` option
+To build for an alternate platform, specify the :option:`!--plat-name` option
 to the build command.  Valid values are currently 'win32', 'win-amd64' and
 'win-ia64'.  For example, on a 32bit version of Windows, you could execute::
 
@@ -383,14 +383,14 @@ The Postinstallation script
 ---------------------------
 
 Starting with Python 2.3, a postinstallation script can be specified with the
-:option:`--install-script` option.  The basename of the script must be
+:option:`!--install-script` option.  The basename of the script must be
 specified, and the script filename must also be listed in the scripts argument
 to the setup function.
 
 This script will be run at installation time on the target system after all the
-files have been copied, with ``argv[1]`` set to :option:`-install`, and again at
+files have been copied, with ``argv[1]`` set to :option:`!-install`, and again at
 uninstallation time before the files are removed with ``argv[1]`` set to
-:option:`-remove`.
+:option:`!-remove`.
 
 The installation script runs embedded in the windows installer, every output
 (``sys.stdout``, ``sys.stderr``) is redirected into a buffer and will be
@@ -453,7 +453,7 @@ built-in functions in the installation script.
 Vista User Access Control (UAC)
 ===============================
 
-Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control`
+Starting with Python 2.6, bdist_wininst supports a :option:`!--user-access-control`
 option.  The default is 'none' (meaning no UAC handling is done), and other
 valid values are 'auto' (meaning prompt for UAC elevation if Python was
 installed for all users) and 'force' (meaning always prompt for elevation).

Doc/distutils/configfile.rst

@@ -66,7 +66,7 @@ universal :option:`!--help` option, e.g. ::
      --swig-opts          list of SWIG command line options
    [...]
 
-Note that an option spelled :option:`--foo-bar` on the command-line  is spelled
+Note that an option spelled :option:`!--foo-bar` on the command-line  is spelled
 ``foo_bar`` in configuration files.
 
 .. _distutils-build-ext-inplace:
@@ -75,12 +75,12 @@ For example, say you want your extensions to be built "in-place"---that is, you
 have an extension :mod:`pkg.ext`, and you want the compiled extension file
 (:file:`ext.so` on Unix, say) to be put in the same source directory as your
 pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`.  You can always use the
-:option:`--inplace` option on the command-line to ensure this::
+:option:`!--inplace` option on the command-line to ensure this::
 
    python setup.py build_ext --inplace
 
 But this requires that you always specify the :command:`build_ext` command
-explicitly, and remember to provide :option:`--inplace`. An easier way is to
+explicitly, and remember to provide :option:`!--inplace`. An easier way is to
 "set and forget" this option, by encoding it in :file:`setup.cfg`, the
 configuration file for this distribution::
 

Doc/distutils/extending.rst

@@ -62,7 +62,7 @@ requiring modifications to the Python installation.  This is expected to allow
 third-party extensions to provide support for additional packaging systems, but
 the commands can be used for anything distutils commands can be used for.  A new
 configuration option, ``command_packages`` (command-line option
-:option:`--command-packages`), can be used to specify additional packages to be
+:option:`!--command-packages`), can be used to specify additional packages to be
 searched for modules implementing commands.  Like all distutils options, this
 can be specified on the command line or in a configuration file.  This option
 can only be set in the ``[global]`` section of a configuration file, or before

Doc/distutils/setupscript.rst

@@ -446,7 +446,7 @@ command line.  Scripts don't require Distutils to do anything very complicated.
 The only clever feature is that if the first line of the script starts with
 ``#!`` and contains the word "python", the Distutils will adjust the first line
 to refer to the current interpreter location. By default, it is replaced with
-the current interpreter location.  The :option:`--executable` (or :option:`-e`)
+the current interpreter location.  The :option:`!--executable` (or :option:`!-e`)
 option will allow the interpreter path to be explicitly overridden.
 
 The ``scripts`` option simply is a list of files to be handled in this

Doc/distutils/sourcedist.rst

@@ -14,7 +14,7 @@ or config file), :command:`sdist` creates the archive of the default format for
 the current platform.  The default format is a gzip'ed tar file
 (:file:`.tar.gz`) on Unix, and ZIP file on Windows.
 
-You can specify as many formats as you like using the :option:`--formats`
+You can specify as many formats as you like using the :option:`!--formats`
 option, for example::
 
    python setup.py sdist --formats=gztar,zip
@@ -147,7 +147,7 @@ matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching
 :file:`examples/sample?/build`.  All of this is done *after* the standard
 include set, so you can exclude files from the standard set with explicit
 instructions in the manifest template.  (Or, you can use the
-:option:`--no-defaults` option to disable the standard set entirely.)  There are
+:option:`!--no-defaults` option to disable the standard set entirely.)  There are
 several other commands available in the manifest template mini-language; see
 section :ref:`sdist-cmd`.
 
@@ -166,8 +166,8 @@ Now we have our complete list of files, which is written to the manifest for
 future reference, and then used to build the source distribution archive(s).
 
 You can disable the default set of included files with the
-:option:`--no-defaults` option, and you can disable the standard exclude set
-with :option:`--no-prune`.
+:option:`!--no-defaults` option, and you can disable the standard exclude set
+with :option:`!--no-prune`.
 
 Following the Distutils' own manifest template, let's trace how the
 :command:`sdist` command builds the list of files to include in the Distutils
@@ -225,12 +225,12 @@ The normal course of operations for the :command:`sdist` command is as follows:
   in) to create the source distribution archive(s)
 
 There are a couple of options that modify this behaviour.  First, use the
-:option:`--no-defaults` and :option:`--no-prune` to disable the standard
+:option:`!--no-defaults` and :option:`!--no-prune` to disable the standard
 "include" and "exclude" sets.
 
 Second, you might just want to (re)generate the manifest, but not create a source
 distribution::
 
    python setup.py sdist --manifest-only
 
-:option:`-o` is a shortcut for :option:`--manifest-only`.
+:option:`!-o` is a shortcut for :option:`!--manifest-only`.

Doc/extending/extending.rst

@@ -886,7 +886,7 @@ The :mod:`gc` module exposes a way to run the detector (the
 :func:`~gc.collect` function), as well as configuration
 interfaces and the ability to disable the detector at runtime.  The cycle
 detector is considered an optional component; though it is included by default,
-it can be disabled at build time using the :option:`--without-cycle-gc` option
+it can be disabled at build time using the :option:`!--without-cycle-gc` option
 to the :program:`configure` script on Unix platforms (including Mac OS X).  If
 the cycle detector is disabled in this way, the :mod:`gc` module will not be
 available.