Index: Doc/library/idle.rst =================================================================== --- Doc/library/idle.rst (revision 82985) +++ Doc/library/idle.rst (working copy) @@ -286,13 +286,13 @@ If there are arguments: -#. If :option:`-e` is used, arguments are files opened for editing and +#. If ``-e`` is used, arguments are files opened for editing and ``sys.argv`` reflects the arguments passed to IDLE itself. -#. Otherwise, if :option:`-c` is used, all arguments are placed in +#. Otherwise, if ``-c`` is used, all arguments are placed in ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``. -#. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first +#. Otherwise, if neither ``-e`` nor ``-c`` is used, the first argument is a script which is executed with the remaining arguments in ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script name is '-', no script is executed but an interactive Python session is started; Index: Doc/library/timeit.rst =================================================================== --- Doc/library/timeit.rst (revision 82985) +++ Doc/library/timeit.rst (working copy) @@ -119,33 +119,33 @@ where the following options are understood: --n N/:option:`--number=N` +``-n N/--number=N`` how many times to execute 'statement' --r N/:option:`--repeat=N` +``-r N/--repeat=N`` how many times to repeat the timer (default 3) --s S/:option:`--setup=S` +``-s S/--setup=S`` statement to be executed once initially (default ``'pass'``) --t/:option:`--time` +``-t/--time`` use :func:`time.time` (default on all platforms but Windows) --c/:option:`--clock` +``-c/--clock`` use :func:`time.clock` (default on Windows) --v/:option:`--verbose` +``-v/--verbose`` print raw timing results; repeat for more digits precision --h/:option:`--help` +``-h/--help`` print a short usage message and exit A multi-line statement may be given by specifying each line as a separate statement argument; indented lines are possible by enclosing an argument in -quotes and using leading spaces. Multiple :option:`-s` options are treated +quotes and using leading spaces. Multiple ``-s`` options are treated similarly. -If :option:`-n` is not given, a suitable number of loops is calculated by trying +If ``-n`` is not given, a suitable number of loops is calculated by trying successive powers of 10 until the total time is at least 0.2 seconds. The default timer function is platform dependent. On Windows, @@ -155,7 +155,7 @@ platform, the default timer functions measure wall clock time, not the CPU time. This means that other processes running on the same computer may interfere with the timing. The best thing to do when accurate timing is necessary is to repeat -the timing a few times and use the best time. The :option:`-r` option is good +the timing a few times and use the best time. The ``-r`` option is good for this; the default of 3 repetitions is probably enough in most cases. On Unix, you can use :func:`time.clock` to measure CPU time. Index: Doc/library/test.rst =================================================================== --- Doc/library/test.rst (revision 82985) +++ Doc/library/test.rst (working copy) @@ -156,24 +156,23 @@ package whose name starts with ``test_``, importing them, and executing the function :func:`test_main` if present. The names of tests to execute may also be passed to the script. Specifying a single regression test (:program:`python -regrtest.py` :option:`test_spam.py`) will minimize output and only print +regrtest.py test_spam.py`) will minimize output and only print whether the test passed or failed and thus minimize output. Running :mod:`test.regrtest` directly allows what resources are available for -tests to use to be set. You do this by using the :option:`-u` command-line -option. Run :program:`python regrtest.py` :option:`-uall` to turn on all -resources; specifying :option:`all` as an option for :option:`-u` enables all +tests to use to be set. You do this by using the ``-u`` command-line +option. Run :program:`python regrtest.py -uall` to turn on all +resources; specifying ``all`` as an option for ``-u`` enables all possible resources. If all but one resource is desired (a more common case), a comma-separated list of resources that are not desired may be listed after -:option:`all`. The command :program:`python regrtest.py` -:option:`-uall,-audio,-largefile` will run :mod:`test.regrtest` with all -resources except the :option:`audio` and :option:`largefile` resources. For a -list of all resources and more command-line options, run :program:`python -regrtest.py` :option:`-h`. +``all``. The command :program:`python regrtest.py -uall,-audio,-largefile` +will run :mod:`test.regrtest` with all resources except the ``audio`` and +``largefile`` resources. For a list of all resources and more command-line +options, run :program:`python regrtest.py -h`. Some other ways to execute the regression tests depend on what platform the -tests are being executed on. On Unix, you can run :program:`make` -:option:`test` at the top-level directory where Python was built. On Windows, +tests are being executed on. On Unix, you can run :program:`make test` +at the top-level directory where Python was built. On Windows, executing :program:`rt.bat` from your :file:`PCBuild` directory will run all regression tests. Index: Doc/library/doctest.rst =================================================================== --- Doc/library/doctest.rst (revision 82985) +++ Doc/library/doctest.rst (working copy) @@ -88,7 +88,7 @@ $ There's no output! That's normal, and it means all the examples worked. Pass -:option:`-v` to the script, and :mod:`doctest` prints a detailed log of what +``-v`` to the script, and :mod:`doctest` prints a detailed log of what it's trying, and prints a summary at the end:: $ python example.py -v @@ -151,7 +151,7 @@ final line of output is ``***Test Failed*** N failures.``, where *N* is the number of examples that failed. -Run it with the :option:`-v` switch instead:: +Run it with the ``-v`` switch instead:: python M.py -v @@ -160,7 +160,7 @@ You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or prohibit it by passing ``verbose=False``. In either of those cases, -``sys.argv`` is not examined by :func:`testmod` (so passing :option:`-v` or not +``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not has no effect). There is also a command line shortcut for running :func:`testmod`. You can @@ -229,7 +229,7 @@ that can be used to tell it to look for files in other locations. Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the -:option:`-v` command-line switch or with the optional keyword argument +``-v`` command-line switch or with the optional keyword argument *verbose*. There is also a command line shortcut for running :func:`testfile`. You can @@ -913,16 +913,18 @@ As your collection of doctest'ed modules grows, you'll want a way to run all their doctests systematically. :mod:`doctest` provides two functions that can be used to create :mod:`unittest` test suites from modules and text files -containing doctests. To integrate with :mod:`unittest` test discovery, include -a :func:`load_tests` function in your test module:: +containing doctests. These test suites can then be run using :mod:`unittest` +test runners:: import unittest import doctest - import my_module_with_doctests + import my_module_with_doctests, and_another - def load_tests(loader, tests, ignore): - tests.addTests(doctest.DocTestSuite(my_module_with_doctests)) - return test + suite = unittest.TestSuite() + for mod in my_module_with_doctests, and_another: + suite.addTest(doctest.DocTestSuite(mod)) + runner = unittest.TextTestRunner() + runner.run(suite) There are two main functions for creating :class:`unittest.TestSuite` instances from text files and modules with doctests: @@ -1377,7 +1379,7 @@ verbosity. If *verbose* is ``True``, then information is printed about each example, as it is run. If *verbose* is ``False``, then only failures are printed. If *verbose* is unspecified, or ``None``, then verbose output is used - iff the command-line switch :option:`-v` is used. + iff the command-line switch ``-v`` is used. The optional keyword argument *optionflags* can be used to control how the test runner compares expected output to actual output, and how it displays failures. Index: Doc/library/unittest.rst =================================================================== --- Doc/library/unittest.rst (revision 82985) +++ Doc/library/unittest.rst (working copy) @@ -220,13 +220,13 @@ unittest supports three command options. -* :option:`-b` / :option:`--buffer` +* ``-b`` / ``--buffer`` The standard output and standard error streams are buffered during the test run. Output during a passing test is discarded. Output is echoed normally on test fail or error and is added to the failure messages. -* :option:`-c` / :option:`--catch` +* ``-c`` / ``--catch`` Control-C during the test run waits for the current test to end and then reports all the results so far. A second control-C raises the normal @@ -234,7 +234,7 @@ See `Signal Handling`_ for the functions that provide this functionality. -* :option:`-f` / :option:`--failfast` +* ``-f`` / ``--failfast`` Stop the test run on the first error or failure. @@ -270,7 +270,7 @@ -t directory Top level directory of project (default to start directory) -The :option:`-s`, :option:`-p`, and :option:`-t` options can be passed in +The ``-s``, ``-p``, and ``-t`` options can be passed in as positional arguments in that order. The following two command lines are equivalent:: @@ -1908,7 +1908,7 @@ Signal Handling --------------- -The :option:`-c`/:option:`--catch` command line option to unittest, along with the ``catchbreak`` +The ``-c``/``--catch`` command line option to unittest, along with the ``catchbreak`` parameter to :func:`unittest.main()`, provide more friendly handling of control-C during a test run. With catch break behavior enabled control-C will allow the currently running test to complete, and the test run will then end Index: Doc/library/pydoc.rst =================================================================== --- Doc/library/pydoc.rst (revision 82985) +++ Doc/library/pydoc.rst (working copy) @@ -40,25 +40,25 @@ executed on that occasion. Use an ``if __name__ == '__main__':`` guard to only execute code when a file is invoked as a script and not just imported. -Specifying a :option:`-w` flag before the argument will cause HTML documentation +Specifying a ``-w`` flag before the argument will cause HTML documentation to be written out to a file in the current directory, instead of displaying text on the console. -Specifying a :option:`-k` flag before the argument will search the synopsis +Specifying a ``-k`` flag before the argument will search the synopsis lines of all available modules for the keyword given as the argument, again in a manner similar to the Unix :program:`man` command. The synopsis line of a module is the first line of its documentation string. You can also use :program:`pydoc` to start an HTTP server on the local machine that will serve documentation to visiting Web browsers. :program:`pydoc` -:option:`-p 1234` will start a HTTP server on port 1234, allowing you to browse +``-p 1234`` will start a HTTP server on port 1234, allowing you to browse the documentation at ``http://localhost:1234/`` in your preferred Web browser. -:program:`pydoc` :option:`-g` will start the server and additionally bring up a +:program:`pydoc` ``-g`` will start the server and additionally bring up a small :mod:`tkinter`\ -based graphical interface to help you search for documentation pages. When :program:`pydoc` generates documentation, it uses the current environment -and path to locate modules. Thus, invoking :program:`pydoc` :option:`spam` +and path to locate modules. Thus, invoking :program:`pydoc spam` documents precisely the version of the module you would get if you started the Python interpreter and typed ``import spam``. Index: Doc/library/webbrowser.rst =================================================================== --- Doc/library/webbrowser.rst (revision 82985) +++ Doc/library/webbrowser.rst (working copy) @@ -31,8 +31,8 @@ The script :program:`webbrowser` can be used as a command-line interface for the module. It accepts an URL as the argument. It accepts the following optional -parameters: :option:`-n` opens the URL in a new browser window, if possible; -:option:`-t` opens the URL in a new browser page ("tab"). The options are, +parameters: ``-n`` opens the URL in a new browser window, if possible; +``-t`` opens the URL in a new browser page ("tab"). The options are, naturally, mutually exclusive. The following exception is defined: Index: Doc/library/compileall.rst =================================================================== --- Doc/library/compileall.rst (revision 82985) +++ Doc/library/compileall.rst (working copy) @@ -12,12 +12,12 @@ This module may also be used as a script (using the :option:`-m` Python flag) to compile Python sources. Directories to recursively traverse (passing -:option:`-l` stops the recursive behavior) for sources are listed on the command +``-l`` stops the recursive behavior) for sources are listed on the command line. If no arguments are given, the invocation is equivalent to ``-l sys.path``. Printing lists of the files compiled can be disabled with the -:option:`-q` flag. In addition, the :option:`-x` option takes a regular +``-q`` flag. In addition, the ``-x`` option takes a regular expression argument. All files that match the expression will be skipped. -The :option:`-b` flag may be given to write legacy ``.pyc`` file path names, +The ``-b`` flag may be given to write legacy ``.pyc`` file path names, otherwise :pep:`3147` style byte-compiled path names are written.