Fix usage of :option: in the docs (#9312). · pythoncapi/cpython@713d303 · GitHub
Skip to content

Commit 713d303

Browse files
merwokmerwok
committed
Fix usage of :option: in the docs (python#9312).
:option: is used to create a link to an option of python, not to mark up any instance of any arbitrary command-line option. These were changed to ````. For modules which do have a command-line interface, lists of options have been properly marked up with the program/cmdoption directives combo. Options defined in such blocks can be linked to with :option: later in the same file, they won’t link to an option of python. Finally, the markup of command-line fragments in optparse.rst has been cleaned to use ``x`` instead of ``"x"``, keeping that latter form for actual Python strings. Patch by Eli Bendersky and Éric Araujo.
1 parent daa29d0 commit 713d303

13 files changed

Lines changed: 216 additions & 159 deletions

‎Doc/library/codecs.rst‎

Lines changed: 1 addition & 1 deletion

‎Doc/library/compileall.rst‎

Lines changed: 47 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,16 +10,53 @@ libraries. These functions compile Python source files in a directory tree,
1010
allowing users without permission to write to the libraries to take advantage of
1111
cached byte-code files.
1212

13-
This module may also be used as a script (using the :option:`-m` Python flag) to
14-
compile Python sources. Directories to recursively traverse (passing
15-
:option:`-l` stops the recursive behavior) for sources are listed on the command
16-
line. If no arguments are given, the invocation is equivalent to ``-l
17-
sys.path``. Printing lists of the files compiled can be disabled with the
18-
:option:`-q` flag. In addition, the :option:`-x` option takes a regular
19-
expression argument. All files that match the expression will be skipped.
20-
The :option:`-b` flag may be given to write legacy ``.pyc`` file path names,
21-
otherwise :pep:`3147` style byte-compiled path names are written.
2213

14+
Command-line use
15+
----------------
16+
17+
This module can work as a script (using :program:`python -m compileall`) to
18+
compile Python sources.
19+
20+
.. program:: compileall
21+
22+
.. cmdoption:: [directory|file]...
23+
24+
Positional arguments are files to compile or directories that contain
25+
source files, traversed recursively. If no argument is given, behave as if
26+
the command line was ``-l <directories from sys.path>``.
27+
28+
.. cmdoption:: -l
29+
30+
Do not recurse.
31+
32+
.. cmdoption:: -f
33+
34+
Force rebuild even if timestamps are up-to-date.
35+
36+
.. cmdoption:: -q
37+
38+
Do not print the list of files compiled.
39+
40+
.. cmdoption:: -d destdir
41+
42+
Purported directory name for error messages.
43+
44+
.. cmdoption:: -x regex
45+
46+
Skip files with a full path that matches given regular expression.
47+
48+
.. cmdoption:: -i list
49+
50+
Expand list with its content (file and directory names).
51+
52+
.. cmdoption:: -b
53+
54+
Write legacy ``.pyc`` file path names. Default is to write :pep:`3147`-style
55+
byte-compiled path names.
56+
57+
58+
Public functions
59+
----------------
2360

2461
.. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False, legacy=False)
2562

@@ -37,7 +74,7 @@ otherwise :pep:`3147` style byte-compiled path names are written.
3774
operation.
3875

3976
If *legacy* is true, old-style ``.pyc`` file path names are written,
40-
otherwise (the default), :pep:`3147` style path names are written.
77+
otherwise (the default), :pep:`3147`-style path names are written.
4178

4279

4380
.. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, legacy=False)
@@ -64,4 +101,3 @@ subdirectory and all its subdirectories::
64101

65102
Module :mod:`py_compile`
66103
Byte-compile a single source file.
67-

‎Doc/library/doctest.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ works its magic::
8888
$
8989

9090
There's no output! That's normal, and it means all the examples worked. Pass
91-
:option:`-v` to the script, and :mod:`doctest` prints a detailed log of what
91+
``-v`` to the script, and :mod:`doctest` prints a detailed log of what
9292
it's trying, and prints a summary at the end::
9393

9494
$ python example.py -v
@@ -151,7 +151,7 @@ example(s) and the cause(s) of the failure(s) are printed to stdout, and the
151151
final line of output is ``***Test Failed*** N failures.``, where *N* is the
152152
number of examples that failed.
153153

154-
Run it with the :option:`-v` switch instead::
154+
Run it with the ``-v`` switch instead::
155155

156156
python M.py -v
157157

@@ -160,7 +160,7 @@ with assorted summaries at the end.
160160

161161
You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or
162162
prohibit it by passing ``verbose=False``. In either of those cases,
163-
``sys.argv`` is not examined by :func:`testmod` (so passing :option:`-v` or not
163+
``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not
164164
has no effect).
165165

166166
There is also a command line shortcut for running :func:`testmod`. You can
@@ -229,7 +229,7 @@ See section :ref:`doctest-basic-api` for a description of the optional arguments
229229
that can be used to tell it to look for files in other locations.
230230

231231
Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the
232-
:option:`-v` command-line switch or with the optional keyword argument
232+
``-v`` command-line switch or with the optional keyword argument
233233
*verbose*.
234234

235235
There is also a command line shortcut for running :func:`testfile`. You can
@@ -1377,7 +1377,7 @@ DocTestRunner objects
13771377
verbosity. If *verbose* is ``True``, then information is printed about each
13781378
example, as it is run. If *verbose* is ``False``, then only failures are
13791379
printed. If *verbose* is unspecified, or ``None``, then verbose output is used
1380-
iff the command-line switch :option:`-v` is used.
1380+
iff the command-line switch ``-v`` is used.
13811381

13821382
The optional keyword argument *optionflags* can be used to control how the test
13831383
runner compares expected output to actual output, and how it displays failures.

‎Doc/library/exceptions.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ The following exceptions are the exceptions that are usually raised.
120120

121121
Raised when a floating point operation fails. This exception is always defined,
122122
but can only be raised when Python is configured with the
123-
:option:`--with-fpectl` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
123+
``--with-fpectl`` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
124124
defined in the :file:`pyconfig.h` file.
125125

126126

‎Doc/library/getopt.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ exception:
4747
empty string. Long options on the command line can be recognized so long as
4848
they provide a prefix of the option name that matches exactly one of the
4949
accepted options. For example, if *longopts* is ``['foo', 'frob']``, the
50-
option :option:`--fo` will match as :option:`--foo`, but :option:`--f` will
50+
option ``--fo`` will match as ``--foo``, but ``--f`` will
5151
not match uniquely, so :exc:`GetoptError` will be raised.
5252

5353
The return value consists of two elements: the first is a list of ``(option,
@@ -68,7 +68,7 @@ exception:
6868
intermixed. The :func:`getopt` function stops processing options as soon as a
6969
non-option argument is encountered.
7070

71-
If the first character of the option string is '+', or if the environment
71+
If the first character of the option string is ``'+'``, or if the environment
7272
variable :envvar:`POSIXLY_CORRECT` is set, then option processing stops as
7373
soon as a non-option argument is encountered.
7474

‎Doc/library/idle.rst‎

Lines changed: 3 additions & 3 deletions

0 commit comments

Comments
 (0)