From df3a1826a11afd32791a32514eae71d4df08228c Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Tue, 18 Feb 2025 22:49:54 +0530 Subject: [PATCH 01/12] gh-130160: use `.. program::` directive for documenting `idle` CLI --- 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..9615d32435601b 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: + idle [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: + + .. code-block:: bash + + idle -c "print('Hello, World!')" + +.. 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'``. 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 ^^^^^^^^^^^^^^^ From 19f6d9c1b555d462ccdfd69a41b08bf225dbe835 Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri <itskanishkp.py@gmail.com> Date: Fri, 21 Feb 2025 20:23:15 +0530 Subject: [PATCH 02/12] fix: some subcommand and docs --- Doc/library/idle.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 9615d32435601b..31d61f4635333f 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -666,13 +666,14 @@ IDLE can be invoked from the command line with various options. The general synt .. code-block:: bash - idle [options] [file ...] + python -m idlelib idle [options] [file ...] The following options are available: .. option:: -c <command> - Run the specified Python command in the shell window. For example: + 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. .. code-block:: bash From 147f909ab853807ee2934d280b599d77dd0e9430 Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri <itskanishkp.py@gmail.com> Date: Fri, 21 Feb 2025 20:39:01 +0530 Subject: [PATCH 03/12] fix: linting errors --- Doc/library/idle.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 31d61f4635333f..ac26153711ffef 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -672,13 +672,10 @@ The following options are available: .. option:: -c <command> - Run the specified Python command in the shell window. For example, pass ``-c "print('Hello, World!')"``. + 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. - .. code-block:: bash - - idle -c "print('Hello, World!')" - .. option:: -d Enable the debugger and open the shell window. From 50805d5cfa6cffcbc98fa772b9637737cd010b08 Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri <itskanishkp.py@gmail.com> Date: Fri, 21 Feb 2025 20:47:15 +0530 Subject: [PATCH 04/12] fix: error in the linting --- Doc/library/idle.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index ac26153711ffef..c658986320acfb 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -672,8 +672,7 @@ The following options are available: .. option:: -c <command> - Run the specified Python command in the shell window. For example, pass ``-c - "print('Hello, World!')"``. + 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 From a6c38bea9eac88498c098d097d761413d42f9719 Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri <itskanishkp.py@gmail.com> Date: Fri, 21 Feb 2025 20:53:09 +0530 Subject: [PATCH 05/12] fix: error Explicit markup ends without a blank line; --- Doc/library/idle.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index c658986320acfb..5146bb0a91cbb0 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -673,6 +673,7 @@ The following options are available: .. option:: -c <command> 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 From a3288f51b1d7d9c6801d9ef95a29a93d3c018faf Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri <itskanishkp.py@gmail.com> Date: Fri, 21 Feb 2025 22:00:08 +0530 Subject: [PATCH 06/12] fix: typo in a subcommand Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/idle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 5146bb0a91cbb0..b53309e29a02e6 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -666,7 +666,7 @@ IDLE can be invoked from the command line with various options. The general synt .. code-block:: bash - python -m idlelib idle [options] [file ...] + python -m idlelib [options] [file ...] The following options are available: From 00683c8429ca165bea0ae4b0fd24f5a7341ea394 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy <tjreedy@udel.edu> Date: Fri, 21 Feb 2025 21:15:18 -0500 Subject: [PATCH 07/12] Update Doc/library/idle.rst --- Doc/library/idle.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index b53309e29a02e6..b5ce437e49922a 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -673,7 +673,6 @@ The following options are available: .. option:: -c <command> 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 From 2e9b8e426658670004c9bc15b717d05935bddc5c Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy <tjreedy@udel.edu> Date: Fri, 21 Feb 2025 21:22:18 -0500 Subject: [PATCH 08/12] Update Doc/library/idle.rst --- Doc/library/idle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index b5ce437e49922a..df8cb15a516813 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -673,7 +673,7 @@ The following options are available: .. option:: -c <command> 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. + On Windows, the outer quotes must be double quotes as shown. .. option:: -d From 9f1eaae70a4bb7b5be6cbf812225b02c2e039faa Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy <tjreedy@udel.edu> Date: Fri, 21 Feb 2025 21:36:51 -0500 Subject: [PATCH 09/12] Update Doc/library/idle.rst --- Doc/library/idle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index df8cb15a516813..72a2966f3bfbda 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -672,7 +672,7 @@ The following options are available: .. option:: -c <command> - Run the specified Python command in the shell window. For example, pass ``-c "print('Hello, World!')"``. + 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 From 7a21e248a34b2f5960aaac840b54d821c0ea7b7a Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy <tjreedy@udel.edu> Date: Fri, 21 Feb 2025 21:41:54 -0500 Subject: [PATCH 10/12] Update Doc/library/idle.rst --- Doc/library/idle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 72a2966f3bfbda..df8cb15a516813 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -672,7 +672,7 @@ The following options are available: .. option:: -c <command> - Run the specified Python command in the shell window. For example, pass ``-c "print('Hello, World!')"``.\ + 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 From 958cecee6dc430c3c363d956daebe2cf78be5057 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy <tjreedy@udel.edu> Date: Sun, 23 Feb 2025 20:55:21 -0500 Subject: [PATCH 11/12] Update Doc/library/idle.rst Split long line. Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/idle.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index df8cb15a516813..d00ce8091f2531 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -672,7 +672,8 @@ The following options are available: .. option:: -c <command> - Run the specified Python command in the shell window. For example, pass ``-c "print('Hello, World!')"``. + 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 From 16730fe7e25002084f301f690bd05bd74f6453b7 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy <tjreedy@udel.edu> Date: Sun, 23 Feb 2025 20:55:49 -0500 Subject: [PATCH 12/12] Update Doc/library/idle.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Emphasize *options*. Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/idle.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index d00ce8091f2531..fabea611e0ebcd 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -710,7 +710,9 @@ The following options are available: 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'``. No editor window is opened, even if that is the default set in the Options dialog. +- 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.