Issue #26462: Doc: avoid literal_block warnings, fix syntax highlighting.
Patch by Julien Palard.
diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst
index 9f59dda..8496676 100644
--- a/Doc/library/2to3.rst
+++ b/Doc/library/2to3.rst
@@ -33,14 +33,18 @@
name = raw_input()
greet(name)
-It can be converted to Python 3.x code via 2to3 on the command line::
+It can be converted to Python 3.x code via 2to3 on the command line:
+
+.. code-block:: shell-session
$ 2to3 example.py
A diff against the original source file is printed. 2to3 can also write the
needed modifications right back to the source file. (A backup of the original
file is made unless :option:`-n` is also given.) Writing the changes back is
-enabled with the :option:`-w` flag::
+enabled with the :option:`-w` flag:
+
+.. code-block:: shell-session
$ 2to3 -w example.py
@@ -57,17 +61,23 @@
By default, 2to3 runs a set of :ref:`predefined fixers <2to3-fixers>`. The
:option:`-l` flag lists all available fixers. An explicit set of fixers to run
can be given with :option:`-f`. Likewise the :option:`!-x` explicitly disables a
-fixer. The following example runs only the ``imports`` and ``has_key`` fixers::
+fixer. The following example runs only the ``imports`` and ``has_key`` fixers:
+
+.. code-block:: shell-session
$ 2to3 -f imports -f has_key example.py
-This command runs every fixer except the ``apply`` fixer::
+This command runs every fixer except the ``apply`` fixer:
+
+.. code-block:: shell-session
$ 2to3 -x apply example.py
Some fixers are *explicit*, meaning they aren't run by default and must be
listed on the command line to be run. Here, in addition to the default fixers,
-the ``idioms`` fixer is run::
+the ``idioms`` fixer is run:
+
+.. code-block:: shell-session
$ 2to3 -f all -f idioms example.py
@@ -113,7 +123,9 @@
The :option:`--add-suffix` option specifies a string to append to all output
filenames. The :option:`-n` flag is required when specifying this as backups
-are not necessary when writing to different filenames. Example::
+are not necessary when writing to different filenames. Example:
+
+.. code-block:: shell-session
$ 2to3 -n -W --add-suffix=3 example.py
@@ -122,7 +134,9 @@
.. versionadded:: 2.7.3
The :option:`--add-suffix` option was added.
-To translate an entire project from one directory tree to another use::
+To translate an entire project from one directory tree to another use:
+
+.. code-block:: shell-session
$ 2to3 --output-dir=python3-version/mycode -W -n python2-version/mycode
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 1dfebc2..bdc699f 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -44,7 +44,9 @@
print args.accumulate(args.integers)
Assuming the Python code above is saved into a file called ``prog.py``, it can
-be run at the command line and provides useful help messages::
+be run at the command line and provides useful help messages:
+
+.. code-block:: shell-session
$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]
@@ -59,7 +61,9 @@
--sum sum the integers (default: find the max)
When run with the appropriate arguments, it prints either the sum or the max of
-the command-line integers::
+the command-line integers:
+
+.. code-block:: shell-session
$ python prog.py 1 2 3 4
4
@@ -67,7 +71,9 @@
$ python prog.py 1 2 3 4 --sum
10
-If invalid arguments are passed in, it will issue an error::
+If invalid arguments are passed in, it will issue an error:
+
+.. code-block:: shell-session
$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
@@ -187,7 +193,9 @@
args = parser.parse_args()
The help for this program will display ``myprogram.py`` as the program name
-(regardless of where the program was invoked from)::
+(regardless of where the program was invoked from):
+
+.. code-block:: shell-session
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
@@ -550,7 +558,9 @@
args = parser.parse_args()
If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser
-help will be printed::
+help will be printed:
+
+.. code-block:: shell-session
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
index cf0c32e..6d5855b 100644
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -113,6 +113,7 @@
The abstract grammar is currently defined as follows:
.. literalinclude:: ../../Parser/Python.asdl
+ :language: none
:mod:`ast` Helpers
diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst
index da15e00..1bfdb39 100644
--- a/Doc/library/cgi.rst
+++ b/Doc/library/cgi.rst
@@ -450,7 +450,9 @@
invoked as a script, the file will dump its environment and the contents of the
form in HTML form. Give it the right mode etc, and send it a request. If it's
installed in the standard :file:`cgi-bin` directory, it should be possible to
-send it a request by entering a URL into your browser of the form::
+send it a request by entering a URL into your browser of the form:
+
+.. code-block:: none
http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
@@ -542,4 +544,3 @@
field values should be supplied in, but knowing whether a request was
received from a conforming browser, or even from a browser at all, is tedious
and error-prone.
-
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index 4558123..43be33e 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -91,14 +91,18 @@
doctest.testmod()
If you run :file:`example.py` directly from the command line, :mod:`doctest`
-works its magic::
+works its magic:
+
+.. code-block:: shell-session
$ python example.py
$
There's no output! That's normal, and it means all the examples worked. Pass
``-v`` to the script, and :mod:`doctest` prints a detailed log of what
-it's trying, and prints a summary at the end::
+it's trying, and prints a summary at the end:
+
+.. code-block:: shell-session
$ python example.py -v
Trying:
@@ -117,7 +121,9 @@
[1, 1, 2, 6, 24, 120]
ok
-And so on, eventually ending with::
+And so on, eventually ending with:
+
+.. code-block:: none
Trying:
factorial(1e100)
@@ -205,7 +211,9 @@
That short script executes and verifies any interactive Python examples
contained in the file :file:`example.txt`. The file content is treated as if it
were a single giant docstring; the file doesn't need to contain a Python
-program! For example, perhaps :file:`example.txt` contains this::
+program! For example, perhaps :file:`example.txt` contains this:
+
+.. code-block:: none
The ``example`` module
======================
diff --git a/Doc/library/htmlparser.rst b/Doc/library/htmlparser.rst
index e73ce07..6740b43 100644
--- a/Doc/library/htmlparser.rst
+++ b/Doc/library/htmlparser.rst
@@ -78,7 +78,9 @@
parser.feed('<html><head><title>Test</title></head>'
'<body><h1>Parse me!</h1></body></html>')
-The output will then be::
+The output will then be:
+
+.. code-block:: none
Encountered a start tag: html
Encountered a start tag: head
diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
index 84805ff..729ca6e 100644
--- a/Doc/library/idle.rst
+++ b/Doc/library/idle.rst
@@ -520,7 +520,7 @@
Command line usage
^^^^^^^^^^^^^^^^^^
-::
+.. code-block:: none
idle.py [-c command] [-d] [-e] [-h] [-i] [-r file] [-s] [-t title] [-] [arg] ...
diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst
index 5460c3a..23333ed 100644
--- a/Doc/library/logging.config.rst
+++ b/Doc/library/logging.config.rst
@@ -209,7 +209,9 @@
handler.
All *other* keys are passed through as keyword arguments to the
- handler's constructor. For example, given the snippet::
+ handler's constructor. For example, given the snippet:
+
+ .. code-block:: yaml
handlers:
console:
@@ -318,7 +320,9 @@
configuration to indicate that a connection exists between the source
and the destination object with that id.
-So, for example, consider the following YAML snippet::
+So, for example, consider the following YAML snippet:
+
+.. code-block:: yaml
formatters:
brief:
@@ -375,7 +379,9 @@
configuration dictionary and which returns the instantiated object.
This is signalled by an absolute import path to the factory being
made available under the special key ``'()'``. Here's a concrete
-example::
+example:
+
+.. code-block:: yaml
formatters:
brief:
@@ -592,7 +598,9 @@
:func:`dictConfig`, so it's worth considering transitioning to this newer
API when it's convenient to do so.
-Examples of these sections in the file are given below. ::
+Examples of these sections in the file are given below.
+
+.. code-block:: ini
[loggers]
keys=root,log02,log03,log04,log05,log06,log07
@@ -604,7 +612,9 @@
keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
The root logger must specify a level and a list of handlers. An example of a
-root logger section is given below. ::
+root logger section is given below.
+
+.. code-block:: ini
[logger_root]
level=NOTSET
@@ -621,7 +631,9 @@
file.
For loggers other than the root logger, some additional information is required.
-This is illustrated by the following example. ::
+This is illustrated by the following example.
+
+.. code-block:: ini
[logger_parser]
level=DEBUG
@@ -639,7 +651,8 @@
say the name used by the application to get the logger.
Sections which specify handler configuration are exemplified by the following.
-::
+
+.. code-block:: ini
[handler_hand01]
class=StreamHandler
@@ -663,7 +676,9 @@
The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging``
package's namespace, is the list of arguments to the constructor for the handler
class. Refer to the constructors for the relevant handlers, or to the examples
-below, to see how typical entries are constructed. ::
+below, to see how typical entries are constructed.
+
+.. code-block:: ini
[handler_hand02]
class=FileHandler
@@ -714,7 +729,9 @@
formatter=form09
args=('localhost:9022', '/log', 'GET')
-Sections which specify formatter configuration are typified by the following. ::
+Sections which specify formatter configuration are typified by the following.
+
+.. code-block:: ini
[formatter_form01]
format=F1 %(asctime)s %(levelname)s %(message)s
@@ -750,5 +767,3 @@
Module :mod:`logging.handlers`
Useful handlers included with the logging module.
-
-
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index c1ed15b..5466462 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -680,7 +680,9 @@
this option on the command line, it expands your ``version`` string (by
replacing ``%prog``), prints it to stdout, and exits.
-For example, if your script is called ``/usr/bin/foo``::
+For example, if your script is called ``/usr/bin/foo``:
+
+.. code-block:: shell-session
$ /usr/bin/foo --version
foo 1.0
@@ -730,14 +732,18 @@
error status 2.
Consider the first example above, where the user passes ``4x`` to an option
-that takes an integer::
+that takes an integer:
+
+.. code-block:: shell-session
$ /usr/bin/foo -n 4x
Usage: foo [options]
foo: error: option -n: invalid integer value: '4x'
-Or, where the user fails to pass a value at all::
+Or, where the user fails to pass a value at all:
+
+.. code-block:: shell-session
$ /usr/bin/foo -n
Usage: foo [options]
diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst
index bb0da9d..ffa042b 100644
--- a/Doc/library/pyexpat.rst
+++ b/Doc/library/pyexpat.rst
@@ -87,7 +87,9 @@
separator.
For example, if *namespace_separator* is set to a space character (``' '``) and
- the following document is parsed::
+ the following document is parsed:
+
+ .. code-block:: xml
<?xml version="1.0"?>
<root xmlns = "http://default-namespace.org/"
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 2bf9680..527cbd0 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -342,7 +342,9 @@
>>> make_archive(archive_name, 'gztar', root_dir)
'/Users/tarek/myarchive.tar.gz'
-The resulting archive contains::
+The resulting archive contains:
+
+.. code-block:: shell-session
$ tar -tzvf /Users/tarek/myarchive.tar.gz
drwx------ tarek/staff 0 2010-02-01 16:23:40 ./
diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst
index a7c3e3e..a81214e 100644
--- a/Doc/library/socketserver.rst
+++ b/Doc/library/socketserver.rst
@@ -481,7 +481,9 @@
The output of the example should look something like this:
-Server::
+Server:
+
+.. code-block:: shell-session
$ python TCPServer.py
127.0.0.1 wrote:
@@ -489,7 +491,9 @@
127.0.0.1 wrote:
python is nice
-Client::
+Client:
+
+.. code-block:: shell-session
$ python TCPClient.py hello world with TCP
Sent: hello world with TCP
@@ -604,7 +608,9 @@
server.server_close()
-The output of the example should look something like this::
+The output of the example should look something like this:
+
+.. code-block:: shell-session
$ python ThreadedTCPServer.py
Server loop running in thread: Thread-1
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 86a42ae..1bb3ac1 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -706,20 +706,23 @@
Replacing /bin/sh shell backquote
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-::
+.. code-block:: bash
output=`mycmd myarg`
- # becomes
- output = check_output(["mycmd", "myarg"])
+becomes::
+
+ output = check_output(["mycmd", "myarg"])
Replacing shell pipeline
^^^^^^^^^^^^^^^^^^^^^^^^
-::
+.. code-block:: bash
output=`dmesg | grep hda`
- # becomes
+
+becomes::
+
p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
p1.stdout.close() # Allow p1 to receive a SIGPIPE if p2 exits.
@@ -729,10 +732,14 @@
to receive a SIGPIPE if p2 exits before p1.
Alternatively, for trusted input, the shell's own pipeline support may still
-be used directly::
+be used directly:
+
+.. code-block:: bash
output=`dmesg | grep hda`
- # becomes
+
+becomes::
+
output=check_output("dmesg | grep hda", shell=True)
diff --git a/Doc/library/zipimport.rst b/Doc/library/zipimport.rst
index 91305f6..e43f2a6 100644
--- a/Doc/library/zipimport.rst
+++ b/Doc/library/zipimport.rst
@@ -149,7 +149,9 @@
--------
Here is an example that imports a module from a ZIP archive - note that the
-:mod:`zipimport` module is not explicitly used. ::
+:mod:`zipimport` module is not explicitly used.
+
+.. code-block:: shell-session
$ unzip -l example.zip
Archive: example.zip