[3.12] Docs: Avoid the deprecated .. cmdoption:: directive (GH-110292) (#110302)

[3.12] Docs: Avoid the deprecated ``.. cmdoption::`` directive (GH-110292).
(cherry picked from commit 77e9aae)

Author: AA-Turner

Doc/library/ast.rst

@@ -2477,26 +2477,26 @@ The following options are accepted:
 
 .. program:: ast
 
-.. cmdoption:: -h, --help
+.. option:: -h, --help
 
    Show the help message and exit.
 
-.. cmdoption:: -m <mode>
-               --mode <mode>
+.. option:: -m <mode>
+            --mode <mode>
 
    Specify what kind of code must be compiled, like the *mode* argument
    in :func:`parse`.
 
-.. cmdoption:: --no-type-comments
+.. option:: --no-type-comments
 
    Don't parse type comments.
 
-.. cmdoption:: -a, --include-attributes
+.. option:: -a, --include-attributes
 
    Include attributes such as line numbers and column offsets.
 
-.. cmdoption:: -i <indent>
-               --indent <indent>
+.. option:: -i <indent>
+            --indent <indent>
 
    Indentation of nodes in AST (number of spaces).
 

Doc/library/compileall.rst

@@ -24,74 +24,74 @@ compile Python sources.
 
 .. program:: compileall
 
-.. cmdoption:: directory ...
-               file ...
+.. option:: directory ...
+            file ...
 
    Positional arguments are files to compile or directories that contain
    source files, traversed recursively.  If no argument is given, behave as if
    the command line was :samp:`-l {<directories from sys.path>}`.
 
-.. cmdoption:: -l
+.. option:: -l
 
    Do not recurse into subdirectories, only compile source code files directly
    contained in the named or implied directories.
 
-.. cmdoption:: -f
+.. option:: -f
 
    Force rebuild even if timestamps are up-to-date.
 
-.. cmdoption:: -q
+.. option:: -q
 
    Do not print the list of files compiled. If passed once, error messages will
    still be printed. If passed twice (``-qq``), all output is suppressed.
 
-.. cmdoption:: -d destdir
+.. option:: -d destdir
 
    Directory prepended to the path to each file being compiled.  This will
    appear in compilation time tracebacks, and is also compiled in to the
    byte-code file, where it will be used in tracebacks and other messages in
    cases where the source file does not exist at the time the byte-code file is
    executed.
 
-.. cmdoption:: -s strip_prefix
-.. cmdoption:: -p prepend_prefix
+.. option:: -s strip_prefix
+.. option:: -p prepend_prefix
 
    Remove (``-s``) or append (``-p``) the given prefix of paths
    recorded in the ``.pyc`` files.
    Cannot be combined with ``-d``.
 
-.. cmdoption:: -x regex
+.. option:: -x regex
 
    regex is used to search the full path to each file considered for
    compilation, and if the regex produces a match, the file is skipped.
 
-.. cmdoption:: -i list
+.. option:: -i list
 
    Read the file ``list`` and add each line that it contains to the list of
    files and directories to compile.  If ``list`` is ``-``, read lines from
    ``stdin``.
 
-.. cmdoption:: -b
+.. option:: -b
 
    Write the byte-code files to their legacy locations and names, which may
    overwrite byte-code files created by another version of Python.  The default
    is to write files to their :pep:`3147` locations and names, which allows
    byte-code files from multiple versions of Python to coexist.
 
-.. cmdoption:: -r
+.. option:: -r
 
    Control the maximum recursion level for subdirectories.
    If this is given, then ``-l`` option will not be taken into account.
    :program:`python -m compileall <directory> -r 0` is equivalent to
    :program:`python -m compileall <directory> -l`.
 
-.. cmdoption:: -j N
+.. option:: -j N
 
    Use *N* workers to compile the files within the given directory.
    If ``0`` is used, then the result of :func:`os.cpu_count()`
    will be used.
 
-.. cmdoption:: --invalidation-mode [timestamp|checked-hash|unchecked-hash]
+.. option:: --invalidation-mode [timestamp|checked-hash|unchecked-hash]
 
    Control how the generated byte-code files are invalidated at runtime.
    The ``timestamp`` value, means that ``.pyc`` files with the source timestamp
@@ -104,17 +104,17 @@ compile Python sources.
    variable is not set, and ``checked-hash`` if the ``SOURCE_DATE_EPOCH``
    environment variable is set.
 
-.. cmdoption:: -o level
+.. option:: -o level
 
    Compile with the given optimization level. May be used multiple times
    to compile for multiple levels at a time (for example,
    ``compileall -o 1 -o 2``).
 
-.. cmdoption:: -e dir
+.. option:: -e dir
 
    Ignore symlinks pointing outside the given directory.
 
-.. cmdoption:: --hardlink-dupes
+.. option:: --hardlink-dupes
 
    If two ``.pyc`` files with different optimization level have
    the same content, use hard links to consolidate duplicate files.

Doc/library/gzip.rst

@@ -266,23 +266,23 @@ Once executed the :mod:`gzip` module keeps the input file(s).
 Command line options
 ^^^^^^^^^^^^^^^^^^^^
 
-.. cmdoption:: file
+.. option:: file
 
    If *file* is not specified, read from :data:`sys.stdin`.
 
-.. cmdoption:: --fast
+.. option:: --fast
 
    Indicates the fastest compression method (less compression).
 
-.. cmdoption:: --best
+.. option:: --best
 
    Indicates the slowest compression method (best compression).
 
-.. cmdoption:: -d, --decompress
+.. option:: -d, --decompress
 
    Decompress the given file.
 
-.. cmdoption:: -h, --help
+.. option:: -h, --help
 
    Show the help message.
 

Doc/library/inspect.rst

@@ -1650,6 +1650,6 @@ By default, accepts the name of a module and prints the source of that
 module. A class or function within the module can be printed instead by
 appended a colon and the qualified name of the target object.
 
-.. cmdoption:: --details
+.. option:: --details
 
    Print information about the specified object rather than the source code

Doc/library/json.rst

@@ -703,7 +703,7 @@ specified, :data:`sys.stdin` and :data:`sys.stdout` will be used respectively:
 Command line options
 ^^^^^^^^^^^^^^^^^^^^
 
-.. cmdoption:: infile
+.. option:: infile
 
    The JSON file to be validated or pretty-printed:
 
@@ -723,36 +723,36 @@ Command line options
 
    If *infile* is not specified, read from :data:`sys.stdin`.
 
-.. cmdoption:: outfile
+.. option:: outfile
 
    Write the output of the *infile* to the given *outfile*. Otherwise, write it
    to :data:`sys.stdout`.
 
-.. cmdoption:: --sort-keys
+.. option:: --sort-keys
 
    Sort the output of dictionaries alphabetically by key.
 
    .. versionadded:: 3.5
 
-.. cmdoption:: --no-ensure-ascii
+.. option:: --no-ensure-ascii
 
    Disable escaping of non-ascii characters, see :func:`json.dumps` for more information.
 
    .. versionadded:: 3.9
 
-.. cmdoption:: --json-lines
+.. option:: --json-lines
 
    Parse every input line as separate JSON object.
 
    .. versionadded:: 3.8
 
-.. cmdoption:: --indent, --tab, --no-indent, --compact
+.. option:: --indent, --tab, --no-indent, --compact
 
    Mutually exclusive options for whitespace control.
 
    .. versionadded:: 3.9
 
-.. cmdoption:: -h, --help
+.. option:: -h, --help
 
    Show the help message.
 

Doc/library/pickletools.rst

@@ -51,24 +51,24 @@ Command line options
 
 .. program:: pickletools
 
-.. cmdoption:: -a, --annotate
+.. option:: -a, --annotate
 
    Annotate each line with a short opcode description.
 
-.. cmdoption:: -o, --output=<file>
+.. option:: -o, --output=<file>
 
    Name of a file where the output should be written.
 
-.. cmdoption:: -l, --indentlevel=<num>
+.. option:: -l, --indentlevel=<num>
 
    The number of blanks by which to indent a new MARK level.
 
-.. cmdoption:: -m, --memo
+.. option:: -m, --memo
 
    When multiple objects are disassembled, preserve memo between
    disassemblies.
 
-.. cmdoption:: -p, --preamble=<preamble>
+.. option:: -p, --preamble=<preamble>
 
    When more than one pickle file are specified, print given preamble
    before each disassembly.

Doc/library/py_compile.rst

@@ -138,13 +138,13 @@ not be compiled.
 
 .. program:: python -m py_compile
 
-.. cmdoption:: <file> ... <fileN>
-               -
+.. option:: <file> ... <fileN>
+            -
 
    Positional arguments are files to compile.  If ``-`` is the only
    parameter, the list of files is taken from standard input.
 
-.. cmdoption:: -q, --quiet
+.. option:: -q, --quiet
 
    Suppress errors output.
 

Doc/library/site.rst

@@ -266,11 +266,11 @@ If it is called without arguments, it will print the contents of
 :data:`USER_BASE` and whether the directory exists, then the same thing for
 :data:`USER_SITE`, and finally the value of :data:`ENABLE_USER_SITE`.
 
-.. cmdoption:: --user-base
+.. option:: --user-base
 
    Print the path to the user base directory.
 
-.. cmdoption:: --user-site
+.. option:: --user-site
 
    Print the path to the user site-packages directory.
 

Doc/library/tarfile.rst

@@ -1151,31 +1151,31 @@ For a list of the files in a tar archive, use the :option:`-l` option:
 Command-line options
 ~~~~~~~~~~~~~~~~~~~~
 
-.. cmdoption:: -l <tarfile>
-               --list <tarfile>
+.. option:: -l <tarfile>
+            --list <tarfile>
 
    List files in a tarfile.
 
-.. cmdoption:: -c <tarfile> <source1> ... <sourceN>
-               --create <tarfile> <source1> ... <sourceN>
+.. option:: -c <tarfile> <source1> ... <sourceN>
+            --create <tarfile> <source1> ... <sourceN>
 
    Create tarfile from source files.
 
-.. cmdoption:: -e <tarfile> [<output_dir>]
-               --extract <tarfile> [<output_dir>]
+.. option:: -e <tarfile> [<output_dir>]
+            --extract <tarfile> [<output_dir>]
 
    Extract tarfile into the current directory if *output_dir* is not specified.
 
-.. cmdoption:: -t <tarfile>
-               --test <tarfile>
+.. option:: -t <tarfile>
+            --test <tarfile>
 
    Test whether the tarfile is valid or not.
 
-.. cmdoption:: -v, --verbose
+.. option:: -v, --verbose
 
    Verbose output.
 
-.. cmdoption:: --filter <filtername>
+.. option:: --filter <filtername>
 
    Specifies the *filter* for ``--extract``.
    See :ref:`tarfile-extraction-filter` for details.

Doc/library/timeit.rst

@@ -214,36 +214,36 @@ Where the following options are understood:
 
 .. program:: timeit
 
-.. cmdoption:: -n N, --number=N
+.. option:: -n N, --number=N
 
    how many times to execute 'statement'
 
-.. cmdoption:: -r N, --repeat=N
+.. option:: -r N, --repeat=N
 
    how many times to repeat the timer (default 5)
 
-.. cmdoption:: -s S, --setup=S
+.. option:: -s S, --setup=S
 
    statement to be executed once initially (default ``pass``)
 
-.. cmdoption:: -p, --process
+.. option:: -p, --process
 
    measure process time, not wallclock time, using :func:`time.process_time`
    instead of :func:`time.perf_counter`, which is the default
 
    .. versionadded:: 3.3
 
-.. cmdoption:: -u, --unit=U
+.. option:: -u, --unit=U
 
    specify a time unit for timer output; can select ``nsec``, ``usec``, ``msec``, or ``sec``
 
    .. versionadded:: 3.5
 
-.. cmdoption:: -v, --verbose
+.. option:: -v, --verbose
 
    print raw timing results; repeat for more digits precision
 
-.. cmdoption:: -h, --help
+.. option:: -h, --help
 
    print a short usage message and exit
 

Doc/library/tokenize.rst

@@ -166,11 +166,11 @@ The following options are accepted:
 
 .. program:: tokenize
 
-.. cmdoption:: -h, --help
+.. option:: -h, --help
 
    show this help message and exit
 
-.. cmdoption:: -e, --exact
+.. option:: -e, --exact
 
    display token names using the exact type