From b2e18fdbb769c7b715134b1f0634c5632c56d95a Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Mon, 24 Feb 2025 07:32:34 +0530 Subject: [PATCH] gh-130160: use `.. program::` directive for documenting `idle` CLI (GH-130278) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --------- Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Terry Jan Reedy Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> (cherry picked from commit 0ff16115741aeaaaf7f963f68d5c575efb960277) Co-authored-by: Kanishk Pachauri --- Doc/library/idle.rst | 68 ++++++++++++++++++++++++++++++++------------ 1 file changed, 50 insertions(+), 18 deletions(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 0aed6f0770dcd0..fabea611e0ebcd 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -660,29 +660,61 @@ functions to be used from IDLE's Python shell. Command line usage ^^^^^^^^^^^^^^^^^^ -.. code-block:: none +.. program:: idle - idle.py [-c command] [-d] [-e] [-h] [-i] [-r file] [-s] [-t title] [-] [arg] ... +IDLE can be invoked from the command line with various options. The general syntax is: - -c command run command in the shell window - -d enable debugger and open shell window - -e open editor window - -h print help message with legal combinations and exit - -i open shell window - -r file run file in shell window - -s run $IDLESTARTUP or $PYTHONSTARTUP first, in shell window - -t title set title of shell window - - run stdin in shell (- must be last option before args) +.. code-block:: bash -If there are arguments: + python -m idlelib [options] [file ...] -* If ``-``, ``-c``, or ``r`` is used, all arguments are placed in - ``sys.argv[1:...]`` and ``sys.argv[0]`` is set to ``''``, ``'-c'``, - or ``'-r'``. No editor window is opened, even if that is the default - set in the Options dialog. +The following options are available: + +.. option:: -c + + Run the specified Python command in the shell window. + For example, pass ``-c "print('Hello, World!')"``. + On Windows, the outer quotes must be double quotes as shown. + +.. option:: -d + + Enable the debugger and open the shell window. + +.. option:: -e + + Open an editor window. + +.. option:: -h + + Print a help message with legal combinations of options and exit. + +.. option:: -i + + Open a shell window. + +.. option:: -r + + Run the specified file in the shell window. + +.. option:: -s + + Run the startup file (as defined by the environment variables :envvar:`IDLESTARTUP` or :envvar:`PYTHONSTARTUP`) before opening the shell window. + +.. option:: -t + + Set the title of the shell window. + +.. option:: - + + Read and execute standard input in the shell window. This option must be the last one before any arguments. + +If arguments are provided: + +- If ``-``, ``-c``, or ``-r`` is used, all arguments are placed in ``sys.argv[1:]``, + and ``sys.argv[0]`` is set to ``''``, ``'-c'``, or ``'-r'`` respectively. + No editor window is opened, even if that is the default set in the *Options* dialog. +- Otherwise, arguments are treated as files to be opened for editing, and ``sys.argv`` reflects the arguments passed to IDLE itself. -* Otherwise, arguments are files opened for editing and - ``sys.argv`` reflects the arguments passed to IDLE itself. Startup failure ^^^^^^^^^^^^^^^