Skip to content

gh-101100: Fix Sphinx warnings in library/cmd.rst #113502

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Dec 27, 2023
Merged

gh-101100: Fix Sphinx warnings in library/cmd.rst #113502

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1756b00
Fix Sphinx warnings in library/cmd.rst
hugovk Dec 26, 2023
6246d22
Link to sys.stdout and sys.stdin
hugovk Dec 27, 2023
8e52437
Merge branch 'main' into docs-fix-sphinx-warnings-cmd
hugovk Dec 27, 2023
32eec77
Add brackets
hugovk Dec 27, 2023
5fba9dd
Don't link to do_help from do_help
hugovk Dec 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 14 additions & 11 deletions Doc/library/cmd.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

All subclasses of :class:`Cmd` inherit a predefined :meth:`do_help`. This

.. 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.
Expand Down Expand Up @@ -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, :data:`sys.stdout.write() <sys.stdout>`
and :data:`sys.stdin.readline() <sys.stdin>` 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.)

Expand All @@ -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
Expand Down
1 change: 0 additions & 1 deletion Doc/tools/.nitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@ Doc/library/asyncio-policy.rst
Doc/library/asyncio-subprocess.rst
Doc/library/asyncio-task.rst
Doc/library/bdb.rst
Doc/library/cmd.rst
Doc/library/collections.rst
Doc/library/concurrent.futures.rst
Doc/library/configparser.rst
Expand Down