From 1756b00672ee69cf6b60d41631b90374ef5f068e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Tue, 26 Dec 2023 22:42:15 +0200 Subject: [PATCH 1/4] Fix Sphinx warnings in library/cmd.rst --- Doc/library/cmd.rst | 23 +++++++++++++---------- Doc/tools/.nitignore | 1 - 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst index a79882ed1cca4f..1cc03bb77af99f 100644 --- a/Doc/library/cmd.rst +++ b/Doc/library/cmd.rst @@ -76,27 +76,30 @@ A :class:`Cmd` instance has the following methods: single: ! (exclamation); in a command interpreter An interpreter instance will recognize a command name ``foo`` if and only if it - has a method :meth:`do_foo`. As a special case, a line beginning with the + has a method :meth:`!do_foo`. As a special case, a line beginning with the character ``'?'`` is dispatched to the method :meth:`do_help`. As another special case, a line beginning with the character ``'!'`` is dispatched to the - method :meth:`do_shell` (if such a method is defined). + method :meth:`!do_shell` (if such a method is defined). This method will return when the :meth:`postcmd` method returns a true value. The *stop* argument to :meth:`postcmd` is the return value from the command's corresponding :meth:`!do_\*` method. If completion is enabled, completing commands will be done automatically, and - completing of commands args is done by calling :meth:`complete_foo` with + completing of commands args is done by calling :meth:`!complete_foo` with arguments *text*, *line*, *begidx*, and *endidx*. *text* is the string prefix we are attempting to match: all returned matches must begin with it. *line* is the current input line with leading whitespace removed, *begidx* and *endidx* are the beginning and ending indexes of the prefix text, which could be used to provide different completion depending upon which position the argument is in. + +.. method:: Cmd.do_help(arg) + All subclasses of :class:`Cmd` inherit a predefined :meth:`do_help`. This method, called with an argument ``'bar'``, invokes the corresponding method - :meth:`help_bar`, and if that is not present, prints the docstring of - :meth:`do_bar`, if available. With no argument, :meth:`do_help` lists all + :meth:`!help_bar`, and if that is not present, prints the docstring of + :meth:`!do_bar`, if available. With no argument, :meth:`do_help` lists all available help topics (that is, all commands with corresponding :meth:`!help_\*` methods or commands that have docstrings), and also lists any undocumented commands. @@ -229,8 +232,8 @@ Instances of :class:`Cmd` subclasses have some public instance variables: .. attribute:: Cmd.use_rawinput A flag, defaulting to true. If true, :meth:`cmdloop` uses :func:`input` to - display a prompt and read the next command; if false, :meth:`sys.stdout.write` - and :meth:`sys.stdin.readline` are used. (This means that by importing + display a prompt and read the next command; if false, :meth:`!sys.stdout.write` + and :meth:`!sys.stdin.readline` are used. (This means that by importing :mod:`readline`, on systems that support it, the interpreter will automatically support :program:`Emacs`\ -like line editing and command-history keystrokes.) @@ -249,14 +252,14 @@ This section presents a simple example of how to build a shell around a few of the commands in the :mod:`turtle` module. Basic turtle commands such as :meth:`~turtle.forward` are added to a -:class:`Cmd` subclass with method named :meth:`do_forward`. The argument is +:class:`Cmd` subclass with method named :meth:`!do_forward`. The argument is converted to a number and dispatched to the turtle module. The docstring is used in the help utility provided by the shell. The example also includes a basic record and playback facility implemented with the :meth:`~Cmd.precmd` method which is responsible for converting the input to -lowercase and writing the commands to a file. The :meth:`do_playback` method -reads the file and adds the recorded commands to the :attr:`cmdqueue` for +lowercase and writing the commands to a file. The :meth:`!do_playback` method +reads the file and adds the recorded commands to the :attr:`~Cmd.cmdqueue` for immediate playback:: import cmd, sys diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 4eb007577e1aaa..48c24e89d6a4e3 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -33,7 +33,6 @@ Doc/library/asyncio-task.rst Doc/library/bdb.rst Doc/library/bisect.rst Doc/library/calendar.rst -Doc/library/cmd.rst Doc/library/collections.rst Doc/library/concurrent.futures.rst Doc/library/configparser.rst From 6246d2200618af4d1cb66d7e83026af2288ceb53 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 27 Dec 2023 11:36:22 +0200 Subject: [PATCH 2/4] Link to sys.stdout and sys.stdin --- Doc/library/cmd.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst index 1cc03bb77af99f..7e84aeca4ea311 100644 --- a/Doc/library/cmd.rst +++ b/Doc/library/cmd.rst @@ -232,8 +232,8 @@ Instances of :class:`Cmd` subclasses have some public instance variables: .. attribute:: Cmd.use_rawinput A flag, defaulting to true. If true, :meth:`cmdloop` uses :func:`input` to - display a prompt and read the next command; if false, :meth:`!sys.stdout.write` - and :meth:`!sys.stdin.readline` are used. (This means that by importing + display a prompt and read the next command; if false, :data:`sys.stdout.write ` + and :data:`sys.stdin.readline ` are used. (This means that by importing :mod:`readline`, on systems that support it, the interpreter will automatically support :program:`Emacs`\ -like line editing and command-history keystrokes.) From 32eec77e39aa149cb1ac485162157bb29561f89e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 27 Dec 2023 02:42:47 -0700 Subject: [PATCH 3/4] Add brackets Co-authored-by: Serhiy Storchaka --- Doc/library/cmd.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst index 7e84aeca4ea311..7a00f09eda5c3a 100644 --- a/Doc/library/cmd.rst +++ b/Doc/library/cmd.rst @@ -232,8 +232,8 @@ Instances of :class:`Cmd` subclasses have some public instance variables: .. attribute:: Cmd.use_rawinput A flag, defaulting to true. If true, :meth:`cmdloop` uses :func:`input` to - display a prompt and read the next command; if false, :data:`sys.stdout.write ` - and :data:`sys.stdin.readline ` are used. (This means that by importing + display a prompt and read the next command; if false, :data:`sys.stdout.write() ` + and :data:`sys.stdin.readline() ` are used. (This means that by importing :mod:`readline`, on systems that support it, the interpreter will automatically support :program:`Emacs`\ -like line editing and command-history keystrokes.) From 5fba9dd4e53892d72352cb8c3ff83c1e628a06ab Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 27 Dec 2023 03:07:21 -0700 Subject: [PATCH 4/4] Don't link to do_help from do_help Co-authored-by: Alex Waygood --- Doc/library/cmd.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst index 7a00f09eda5c3a..39ef4b481478d1 100644 --- a/Doc/library/cmd.rst +++ b/Doc/library/cmd.rst @@ -96,10 +96,10 @@ A :class:`Cmd` instance has the following methods: .. method:: Cmd.do_help(arg) - All subclasses of :class:`Cmd` inherit a predefined :meth:`do_help`. This + All subclasses of :class:`Cmd` inherit a predefined :meth:`!do_help`. This method, called with an argument ``'bar'``, invokes the corresponding method :meth:`!help_bar`, and if that is not present, prints the docstring of - :meth:`!do_bar`, if available. With no argument, :meth:`do_help` lists all + :meth:`!do_bar`, if available. With no argument, :meth:`!do_help` lists all available help topics (that is, all commands with corresponding :meth:`!help_\*` methods or commands that have docstrings), and also lists any undocumented commands.