Issue #26638: Fix links to some CLI options and section headings
* Disable inappropriate links to Python interpreter options * Correct link to CLI section in zipapp * Make CLI section label in timeit less ambiguous
This commit is contained in:
Martin Panter
parent
b4912b8ed3
commit
00ccacc8db
|
|
@ -319,12 +319,12 @@ 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
|
||||
means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define
|
||||
(: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`).
|
||||
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++.
|
||||
|
||||
|
|
@ -799,7 +799,7 @@ This module provides the :class:`UnixCCompiler` class, a subclass of
|
|||
|
||||
* library search directories specified with :option:`-Ldir`
|
||||
|
||||
* compile handled by :program:`cc` (or similar) executable with :option:`-c`
|
||||
* 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
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ option values can be split across multiple lines simply by indenting the
|
|||
continuation lines.
|
||||
|
||||
You can find out the list of options supported by a particular command with the
|
||||
universal :option:`--help` option, e.g. ::
|
||||
universal :option:`!--help` option, e.g. ::
|
||||
|
||||
> python setup.py --help build_ext
|
||||
[...]
|
||||
|
|
|
|||
|
|
@ -865,12 +865,12 @@ config file will apply. (Or if other commands that derive values from it are
|
|||
run, they will use the values in the config file.)
|
||||
|
||||
You can find out the complete list of options for any command using the
|
||||
:option:`--help` option, e.g.::
|
||||
:option:`!--help` option, e.g.::
|
||||
|
||||
python setup.py build --help
|
||||
|
||||
and you can find out the complete list of global options by using
|
||||
:option:`--help` without a command::
|
||||
:option:`!--help` without a command::
|
||||
|
||||
python setup.py --help
|
||||
|
||||
|
|
@ -927,7 +927,7 @@ 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`.
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ Comments and exact indentation are preserved throughout the translation process.
|
|||
|
||||
By default, 2to3 runs a set of :ref:`predefined fixers <2to3-fixers>`. The
|
||||
:option:`-l` flag lists all available fixers. An explicit set of fixers to run
|
||||
can be given with :option:`-f`. Likewise the :option:`-x` explicitly disables a
|
||||
can be given with :option:`-f`. Likewise the :option:`!-x` explicitly disables a
|
||||
fixer. The following example runs only the ``imports`` and ``has_key`` fixers::
|
||||
|
||||
$ 2to3 -f imports -f has_key example.py
|
||||
|
|
@ -78,12 +78,12 @@ but 2to3 cannot fix automatically. In this case, 2to3 will print a warning
|
|||
beneath the diff for a file. You should address the warning in order to have
|
||||
compliant 3.x code.
|
||||
|
||||
2to3 can also refactor doctests. To enable this mode, use the :option:`-d`
|
||||
2to3 can also refactor doctests. To enable this mode, use the :option:`!-d`
|
||||
flag. Note that *only* doctests will be refactored. This also doesn't require
|
||||
the module to be valid Python. For example, doctest like examples in a reST
|
||||
document could also be refactored with this option.
|
||||
|
||||
The :option:`-v` option enables output of more information on the translation
|
||||
The :option:`!-v` option enables output of more information on the translation
|
||||
process.
|
||||
|
||||
Since some print statements can be parsed as function calls or statements, 2to3
|
||||
|
|
@ -102,14 +102,14 @@ when not overwriting the input files.
|
|||
.. versionadded:: 3.2.3
|
||||
The :option:`-o` option was added.
|
||||
|
||||
The :option:`-W` or :option:`--write-unchanged-files` flag tells 2to3 to always
|
||||
The :option:`!-W` or :option:`--write-unchanged-files` flag tells 2to3 to always
|
||||
write output files even if no changes were required to the file. This is most
|
||||
useful with :option:`-o` so that an entire Python source tree is copied with
|
||||
translation from one directory to another.
|
||||
This option implies the :option:`-w` flag as it would not make sense otherwise.
|
||||
|
||||
.. versionadded:: 3.2.3
|
||||
The :option:`-W` flag was added.
|
||||
The :option:`!-W` flag was added.
|
||||
|
||||
The :option:`--add-suffix` option specifies a string to append to all output
|
||||
filenames. The :option:`-n` flag is required when specifying this as backups
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
--------------
|
||||
|
||||
This module provides a simple way to time small bits of Python code. It has both
|
||||
a :ref:`command-line-interface` as well as a :ref:`callable <python-interface>`
|
||||
a :ref:`timeit-command-line-interface` as well as a :ref:`callable <python-interface>`
|
||||
one. It avoids a number of common traps for measuring execution times.
|
||||
See also Tim Peters' introduction to the "Algorithms" chapter in the *Python
|
||||
Cookbook*, published by O'Reilly.
|
||||
|
|
@ -23,7 +23,7 @@ Cookbook*, published by O'Reilly.
|
|||
Basic Examples
|
||||
--------------
|
||||
|
||||
The following example shows how the :ref:`command-line-interface`
|
||||
The following example shows how the :ref:`timeit-command-line-interface`
|
||||
can be used to compare three different expressions:
|
||||
|
||||
.. code-block:: sh
|
||||
|
|
@ -174,7 +174,7 @@ The module defines three convenience functions and a public class:
|
|||
where the traceback is sent; it defaults to :data:`sys.stderr`.
|
||||
|
||||
|
||||
.. _command-line-interface:
|
||||
.. _timeit-command-line-interface:
|
||||
|
||||
Command-Line Interface
|
||||
----------------------
|
||||
|
|
|
|||
|
|
@ -265,7 +265,7 @@ Updating Code For New Versions of Python
|
|||
|
||||
Warnings that are only of interest to the developer are ignored by default. As
|
||||
such you should make sure to test your code with typically ignored warnings
|
||||
made visible. You can do this from the command-line by passing :option:`-Wd`
|
||||
made visible. You can do this from the command-line by passing :option:`-Wd <-W>`
|
||||
to the interpreter (this is shorthand for :option:`-W default`). This enables
|
||||
default handling for all warnings, including those that are ignored by default.
|
||||
To change what action is taken for encountered warnings you simply change what
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ Python code, which can be :ref:`executed directly by the Python interpreter
|
|||
Basic Example
|
||||
-------------
|
||||
|
||||
The following example shows how the :ref:`command-line-interface`
|
||||
The following example shows how the :ref:`zipapp-command-line-interface`
|
||||
can be used to create an executable archive from a directory containing
|
||||
Python code. When run, the archive will execute the ``main`` function from
|
||||
the module ``myapp`` in the archive.
|
||||
|
|
|
|||
|
|
@ -1057,7 +1057,7 @@ Here are all of the changes that Python 2.3 makes to the core Python language.
|
|||
* A new warning, :exc:`PendingDeprecationWarning` was added to indicate features
|
||||
which are in the process of being deprecated. The warning will *not* be printed
|
||||
by default. To check for use of features that will be deprecated in the future,
|
||||
supply :option:`-Walways::PendingDeprecationWarning::` on the command line or
|
||||
supply :option:`-Walways::PendingDeprecationWarning:: <-W>` on the command line or
|
||||
use :func:`warnings.filterwarnings`.
|
||||
|
||||
* The process of deprecating string-based exceptions, as in ``raise "Error
|
||||
|
|
@ -1734,7 +1734,7 @@ The optparse Module
|
|||
The :mod:`getopt` module provides simple parsing of command-line arguments. The
|
||||
new :mod:`optparse` module (originally named Optik) provides more elaborate
|
||||
command-line parsing that follows the Unix conventions, automatically creates
|
||||
the output for :option:`--help`, and can perform different actions for different
|
||||
the output for :option:`!--help`, and can perform different actions for different
|
||||
options.
|
||||
|
||||
You start by creating an instance of :class:`OptionParser` and telling it what
|
||||
|
|
@ -1973,7 +1973,7 @@ Some of the more notable changes are:
|
|||
the Python program as part of its execution.
|
||||
|
||||
* The :file:`regrtest.py` script now provides a way to allow "all resources
|
||||
except *foo*." A resource name passed to the :option:`-u` option can now be
|
||||
except *foo*." A resource name passed to the :option:`!-u` option can now be
|
||||
prefixed with a hyphen (``'-'``) to mean "remove this resource." For example,
|
||||
the option '``-uall,-bsddb``' could be used to enable the use of all resources
|
||||
except ``bsddb``.
|
||||
|
|
|
|||
|
|
@ -1483,8 +1483,8 @@ Some of the changes to Python's build process and to the C API are:
|
|||
intended as an aid to people developing the Python core. Providing
|
||||
:option:`----enable-profiling` to the :program:`configure` script will let you
|
||||
profile the interpreter with :program:`gprof`, and providing the
|
||||
:option:`----with-tsc` switch enables profiling using the Pentium's Time-Stamp-
|
||||
Counter register. Note that the :option:`----with-tsc` switch is slightly
|
||||
:option:`--with-tsc` switch enables profiling using the Pentium's Time-Stamp-
|
||||
Counter register. Note that the :option:`--with-tsc` switch is slightly
|
||||
misnamed, because the profiling feature also works on the PowerPC platform,
|
||||
though that processor architecture doesn't call that register "the TSC
|
||||
register". (Contributed by Jeremy Hylton.)
|
||||
|
|
|
|||
|
|
@ -1095,7 +1095,7 @@ Here are all of the changes that Python 2.5 makes to the core Python language.
|
|||
log all the paths searched. In Python 2.5, a new :exc:`ImportWarning` warning is
|
||||
triggered when an import would have picked up a directory as a package but no
|
||||
:file:`__init__.py` was found. This warning is silently ignored by default;
|
||||
provide the :option:`-Wd` option when running the Python executable to display
|
||||
provide the :option:`-Wd <-W>` option when running the Python executable to display
|
||||
the warning message. (Implemented by Thomas Wouters.)
|
||||
|
||||
* The list of base classes in a class definition can now be empty. As an
|
||||
|
|
@ -1126,7 +1126,7 @@ or ``exit()`` will now exit the interpreter as they expect. (Implemented by
|
|||
Georg Brandl.)
|
||||
|
||||
The Python executable now accepts the standard long options :option:`--help`
|
||||
and :option:`--version`; on Windows, it also accepts the :option:`/?` option
|
||||
and :option:`--version`; on Windows, it also accepts the :option:`/? <-?>` option
|
||||
for displaying a help message. (Implemented by Georg Brandl.)
|
||||
|
||||
.. ======================================================================
|
||||
|
|
@ -1640,7 +1640,7 @@ complete list of changes, or look through the SVN logs for all the details.
|
|||
* The :mod:`webbrowser` module received a number of enhancements. It's now
|
||||
usable as a script with ``python -m webbrowser``, taking a URL as the argument;
|
||||
there are a number of switches to control the behaviour (:option:`-n` for a new
|
||||
browser window, :option:`-t` for a new tab). New module-level functions,
|
||||
browser window, :option:`!-t` for a new tab). New module-level functions,
|
||||
:func:`open_new` and :func:`open_new_tab`, were added to support this. The
|
||||
module's :func:`open` function supports an additional feature, an *autoraise*
|
||||
parameter that signals whether to raise the open window when possible. A number
|
||||
|
|
|
|||
|
|
@ -1820,12 +1820,12 @@ Consult the :mod:`unittest` module documentation for more details.
|
|||
|
||||
The :func:`~unittest.main` function supports some other new options:
|
||||
|
||||
* :option:`-b` or :option:`--buffer` will buffer the standard output
|
||||
* :option:`-b <unittest -b>` or :option:`--buffer` will buffer the standard output
|
||||
and standard error streams during each test. If the test passes,
|
||||
any resulting output will be discarded; on failure, the buffered
|
||||
output will be displayed.
|
||||
|
||||
* :option:`-c` or :option:`--catch` will cause the control-C interrupt
|
||||
* :option:`-c <unittest -c>` or :option:`--catch` will cause the control-C interrupt
|
||||
to be handled more gracefully. Instead of interrupting the test
|
||||
process immediately, the currently running test will be completed
|
||||
and then the partial results up to the interruption will be reported.
|
||||
|
|
@ -1839,7 +1839,7 @@ The :func:`~unittest.main` function supports some other new options:
|
|||
:func:`~unittest.removeHandler` decorator that can be used to mark tests that
|
||||
should have the control-C handling disabled.
|
||||
|
||||
* :option:`-f` or :option:`--failfast` makes
|
||||
* :option:`-f <unittest -f>` or :option:`--failfast` makes
|
||||
test execution stop immediately when a test fails instead of
|
||||
continuing to execute further tests. (Suggested by Cliff Dyer and
|
||||
implemented by Michael Foord; :issue:`8074`.)
|
||||
|
|
@ -2381,7 +2381,7 @@ Other Changes and Fixes
|
|||
takes an integer specifying how many tests run in parallel. This
|
||||
allows reducing the total runtime on multi-core machines.
|
||||
This option is compatible with several other options, including the
|
||||
:option:`-R` switch which is known to produce long runtimes.
|
||||
:option:`!-R` switch which is known to produce long runtimes.
|
||||
(Added by Antoine Pitrou, :issue:`6152`.) This can also be used
|
||||
with a new :option:`-F` switch that runs selected tests in a loop
|
||||
until they fail. (Added by Antoine Pitrou; :issue:`7312`.)
|
||||
|
|
|
|||
Loading…
Reference in New Issue