Improve highlighting of some code blocks. (GH-6401)

8 files changed, 154 insertions, 64 deletions

diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst
index 9d770f5..e78a022 100644
--- a/Doc/howto/argparse.rst
+++ b/Doc/howto/argparse.rst
@@ -24,7 +24,7 @@ Concepts
 Let's show the sort of functionality that we are going to explore in this
 introductory tutorial by making use of the :command:`ls` command:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ ls
    cpython  devguide  prog.py  pypy  rm-unused-function.patch
@@ -77,7 +77,7 @@ Let us start with a very simple example which does (almost) nothing::
 
 Following is a result of running the code:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py
    $ python3 prog.py --help
@@ -119,7 +119,7 @@ An example::
 
 And running the code:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py
    usage: prog.py [-h] echo
@@ -164,7 +164,7 @@ by reading the source code. So, let's make it a bit more useful::
 
 And we get:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py -h
    usage: prog.py [-h] echo
@@ -185,7 +185,7 @@ Now, how about doing something even more useful::
 
 Following is a result of running the code:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py 4
    Traceback (most recent call last):
@@ -206,7 +206,7 @@ give it as strings, unless we tell it otherwise. So, let's tell
 
 Following is a result of running the code:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py 4
    16
@@ -233,7 +233,7 @@ have a look on how to add optional ones::
 
 And the output:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py --verbosity 1
    verbosity turned on
@@ -279,7 +279,7 @@ Let's modify the code accordingly::
 
 And the output:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py --verbose
    verbosity turned on
@@ -325,7 +325,7 @@ versions of the options. It's quite simple::
 
 And here goes:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py -v
    verbosity turned on
@@ -359,7 +359,7 @@ Our program keeps growing in complexity::
 
 And now the output:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py
    usage: prog.py [-h] [-v] square
@@ -395,7 +395,7 @@ multiple verbosity values, and actually get to use them::
 
 And the output:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py 4
    16
@@ -429,7 +429,7 @@ Let's fix it by restricting the values the ``--verbosity`` option can accept::
 
 And the output:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py 4 -v 3
    usage: prog.py [-h] [-v {0,1,2}] square
@@ -470,7 +470,7 @@ verbosity argument (check the output of ``python --help``)::
 We have introduced another action, "count",
 to count the number of occurrences of a specific optional arguments:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py 4
    16
@@ -537,7 +537,7 @@ Let's fix::
 
 And this is what it gives:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py 4 -vvv
    the square of 4 equals 16
@@ -581,7 +581,7 @@ it gets the ``None`` value, and that cannot be compared to an int value
 
 And:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py 4
    16
@@ -614,7 +614,7 @@ not just squares::
 
 Output:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py
    usage: prog.py [-h] [-v] x y
@@ -652,7 +652,7 @@ to display *more* text instead::
 
 Output:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py 4 2
    16
@@ -695,7 +695,7 @@ which will be the opposite of the ``--verbose`` one::
 Our program is now simpler, and we've lost some functionality for the sake of
 demonstration. Anyways, here's the output:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py 4 2
    4^2 == 16
@@ -739,7 +739,7 @@ Note that slight difference in the usage text. Note the ``[-v | -q]``,
 which tells us that we can either use ``-v`` or ``-q``,
 but not both at the same time:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 prog.py --help
    usage: prog.py [-h] [-v | -q] x y
diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index d3c7d66..788a0ee 100644
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -267,12 +267,16 @@ Let's dive in!
    should get its own line.  All the parameter lines should be
    indented from the function name and the docstring.
 
-   The general form of these parameter lines is as follows::
+   The general form of these parameter lines is as follows:
+
+   .. code-block:: none
 
        name_of_parameter: converter
 
    If the parameter has a default value, add that after the
-   converter::
+   converter:
+
+   .. code-block:: none
 
        name_of_parameter: converter = default_value
 
@@ -925,13 +929,17 @@ Parameter default values
 ------------------------
 
 Default values for parameters can be any of a number of values.
-At their simplest, they can be string, int, or float literals::
+At their simplest, they can be string, int, or float literals:
+
+.. code-block:: none
 
     foo: str = "abc"
     bar: int = 123
     bat: float = 45.6
 
-They can also use any of Python's built-in constants::
+They can also use any of Python's built-in constants:
+
+.. code-block:: none
 
     yep:  bool = True
     nope: bool = False
@@ -959,7 +967,9 @@ It can be an entire expression, using math operators and looking up attributes
 on objects.  However, this support isn't exactly simple, because of some
 non-obvious semantics.
 
-Consider the following example::
+Consider the following example:
+
+.. code-block:: none
 
     foo: Py_ssize_t = sys.maxsize - 1
 
@@ -970,7 +980,9 @@ runtime, when the user asks for the function's signature.
 
 What namespace is available when the expression is evaluated?  It's evaluated
 in the context of the module the builtin came from.  So, if your module has an
-attribute called "``max_widgets``", you may simply use it::
+attribute called "``max_widgets``", you may simply use it:
+
+.. code-block:: none
 
     foo: Py_ssize_t = max_widgets
 
@@ -982,7 +994,9 @@ it's best to restrict yourself to modules that are preloaded by Python itself.)
 Evaluating default values only at runtime means Argument Clinic can't compute
 the correct equivalent C default value.  So you need to tell it explicitly.
 When you use an expression, you must also specify the equivalent expression
-in C, using the ``c_default`` parameter to the converter::
+in C, using the ``c_default`` parameter to the converter:
+
+.. code-block:: none
 
     foo: Py_ssize_t(c_default="PY_SSIZE_T_MAX - 1") = sys.maxsize - 1
 
@@ -1359,7 +1373,9 @@ Let's start with defining some terminology:
   A field, in this context, is a subsection of Clinic's output.
   For example, the ``#define`` for the ``PyMethodDef`` structure
   is a field, called ``methoddef_define``.  Clinic has seven
-  different fields it can output per function definition::
+  different fields it can output per function definition:
+
+  .. code-block:: none
 
       docstring_prototype
       docstring_definition
@@ -1416,7 +1432,9 @@ Let's start with defining some terminology:
 
 Clinic defines five new directives that let you reconfigure its output.
 
-The first new directive is ``dump``::
+The first new directive is ``dump``:
+
+.. code-block:: none
 
    dump <destination>
 
@@ -1425,7 +1443,9 @@ the current block, and empties it.  This only works with ``buffer`` and
 ``two-pass`` destinations.
 
 The second new directive is ``output``.  The most basic form of ``output``
-is like this::
+is like this:
+
+.. code-block:: none
 
     output <field> <destination>
 
@@ -1433,7 +1453,9 @@ This tells Clinic to output *field* to *destination*.  ``output`` also
 supports a special meta-destination, called ``everything``, which tells
 Clinic to output *all* fields to that *destination*.
 
-``output`` has a number of other functions::
+``output`` has a number of other functions:
+
+.. code-block:: none
 
     output push
     output pop
@@ -1508,7 +1530,9 @@ preset configurations, as follows:
     Suppresses the ``impl_prototype``, write the ``docstring_definition``
     and ``parser_definition`` to ``buffer``, write everything else to ``block``.
 
-The third new directive is ``destination``::
+The third new directive is ``destination``:
+
+.. code-block:: none
 
     destination <name> <command> [...]
 
@@ -1516,7 +1540,9 @@ This performs an operation on the destination named ``name``.
 
 There are two defined subcommands: ``new`` and ``clear``.
 
-The ``new`` subcommand works like this::
+The ``new`` subcommand works like this:
+
+.. code-block:: none
 
     destination <name> new <type>
 
@@ -1564,7 +1590,9 @@ There are five destination types:
         A two-pass buffer, like the "two-pass" builtin destination above.
 
 
-The ``clear`` subcommand works like this::
+The ``clear`` subcommand works like this:
+
+.. code-block:: none
 
     destination <name> clear
 
@@ -1572,7 +1600,9 @@ It removes all the accumulated text up to this point in the destination.
 (I don't know what you'd need this for, but I thought maybe it'd be
 useful while someone's experimenting.)
 
-The fourth new directive is ``set``::
+The fourth new directive is ``set``:
+
+.. code-block:: none
 
     set line_prefix "string"
     set line_suffix "string"
@@ -1590,7 +1620,9 @@ Both of these support two format strings:
     Turns into the string ``*/``, the end-comment text sequence for C files.
 
 The final new directive is one you shouldn't need to use directly,
-called ``preserve``::
+called ``preserve``:
+
+.. code-block:: none
 
     preserve
 
@@ -1638,7 +1670,9 @@ like so::
     #endif /* HAVE_FUNCTIONNAME */
 
 Then, remove those three lines from the ``PyMethodDef`` structure,
-replacing them with the macro Argument Clinic generated::
+replacing them with the macro Argument Clinic generated:
+
+.. code-block:: none
 
     MODULE_FUNCTIONNAME_METHODDEF
 
diff --git a/Doc/howto/instrumentation.rst b/Doc/howto/instrumentation.rst
index b9c51a4..b63c43c 100644
--- a/Doc/howto/instrumentation.rst
+++ b/Doc/howto/instrumentation.rst
@@ -254,11 +254,15 @@ and the remainder indicates the call/return hierarchy as the script executes.
 
 For a `--enable-shared` build of CPython, the markers are contained within the
 libpython shared library, and the probe's dotted path needs to reflect this. For
-example, this line from the above example::
+example, this line from the above example:
+
+.. code-block:: none
 
    probe process("python").mark("function__entry") {
 
-should instead read::
+should instead read:
+
+.. code-block:: none
 
    probe process("python").library("libpython3.6dm.so.1.0").mark("function__entry") {
 
diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst
index 4d2d052..fdf7874 100644
--- a/Doc/howto/logging-cookbook.rst
+++ b/Doc/howto/logging-cookbook.rst
@@ -72,7 +72,9 @@ Here is the auxiliary module::
     def some_function():
         module_logger.info('received a call to "some_function"')
 
-The output looks like this::
+The output looks like this:
+
+.. code-block:: none
 
     2005-03-23 23:47:11,663 - spam_application - INFO -
        creating an instance of auxiliary_module.Auxiliary
@@ -127,7 +129,9 @@ shows logging from the main (initial) thread and another thread::
     if __name__ == '__main__':
         main()
 
-When run, the script should print something like the following::
+When run, the script should print something like the following:
+
+.. code-block:: none
 
      0 Thread-1 Hi from myfunc
      3 MainThread Hello from main
@@ -240,14 +244,18 @@ messages should not. Here's how you can achieve this::
    logger2.warning('Jail zesty vixen who grabbed pay from quack.')
    logger2.error('The five boxing wizards jump quickly.')
 
-When you run this, on the console you will see ::
+When you run this, on the console you will see
+
+.. code-block:: none
 
    root        : INFO     Jackdaws love my big sphinx of quartz.
    myapp.area1 : INFO     How quickly daft jumping zebras vex.
    myapp.area2 : WARNING  Jail zesty vixen who grabbed pay from quack.
    myapp.area2 : ERROR    The five boxing wizards jump quickly.
 
-and in the file you will see something like ::
+and in the file you will see something like
+
+.. code-block:: none
 
    10-22 22:19 root         INFO     Jackdaws love my big sphinx of quartz.
    10-22 22:19 myapp.area1  DEBUG    Quick zephyrs blow, vexing daft Jim.
@@ -515,7 +523,9 @@ module. Here is a basic working example::
        main()
 
 First run the server, and then the client. On the client side, nothing is
-printed on the console; on the server side, you should see something like::
+printed on the console; on the server side, you should see something like:
+
+.. code-block:: none
 
    About to start TCP server...
       59 root            INFO     Jackdaws love my big sphinx of quartz.
@@ -675,7 +685,9 @@ script::
             lvlname = logging.getLevelName(lvl)
             a2.log(lvl, 'A message at %s level with %d %s', lvlname, 2, 'parameters')
 
-which, when run, produces something like::
+which, when run, produces something like:
+
+.. code-block:: none
 
     2010-09-06 22:38:15,292 a.b.c DEBUG    IP: 123.231.231.123 User: fred     A debug message
     2010-09-06 22:38:15,300 a.b.c INFO     IP: 192.168.0.1     User: sheila   An info message with some parameters
@@ -976,7 +988,9 @@ logging package provides a :class:`~handlers.RotatingFileHandler`::
        print(filename)
 
 The result should be 6 separate files, each with part of the log history for the
-application::
+application:
+
+.. code-block:: none
 
    logging_rotatingfile_example.out
    logging_rotatingfile_example.out.1
@@ -1706,7 +1720,9 @@ which uses JSON to serialise the event in a machine-parseable manner::
     logging.basicConfig(level=logging.INFO, format='%(message)s')
     logging.info(_('message 1', foo='bar', bar='baz', num=123, fnum=123.456))
 
-If the above script is run, it prints::
+If the above script is run, it prints:
+
+.. code-block:: none
 
     message 1 >>> {"fnum": 123.456, "num": 123, "bar": "baz", "foo": "bar"}
 
@@ -1753,7 +1769,9 @@ as in the following complete example::
     if __name__ == '__main__':
         main()
 
-When the above script is run, it prints::
+When the above script is run, it prints:
+
+.. code-block:: none
 
     message 1 >>> {"snowman": "\u2603", "set_value": [1, 2, 3]}
 
@@ -2083,7 +2101,9 @@ most obvious, but you can provide any callable which returns a
 
 This example shows how you can pass configuration data to the callable which
 constructs the instance, in the form of keyword parameters. When run, the above
-script will print::
+script will print:
+
+.. code-block:: none
 
     changed: hello
 
@@ -2150,7 +2170,9 @@ class, as shown in the following example::
     if __name__ == '__main__':
         main()
 
-When run, this produces a file with exactly two lines::
+When run, this produces a file with exactly two lines:
+
+.. code-block:: none
 
     28/01/2015 07:21:23|INFO|Sample message|
     28/01/2015 07:21:23|ERROR|ZeroDivisionError: integer division or modulo by zero|'Traceback (most recent call last):\n  File "logtest7.py", line 30, in main\n    x = 1 / 0\nZeroDivisionError: integer division or modulo by zero'|
@@ -2312,7 +2334,9 @@ Here's the script::
         write_line('Calling decorated foo with True')
         assert decorated_foo(True)
 
-When this script is run, the following output should be observed::
+When this script is run, the following output should be observed:
+
+.. code-block:: none
 
     Calling undecorated foo with False
     about to log at DEBUG ...
@@ -2408,7 +2432,9 @@ the following complete example::
         logging.config.dictConfig(LOGGING)
         logging.warning('The local time is %s', time.asctime())
 
-When this script is run, it should print something like::
+When this script is run, it should print something like:
+
+.. code-block:: none
 
     2015-10-17 12:53:29,501 The local time is Sat Oct 17 13:53:29 2015
     2015-10-17 13:53:29,501 The local time is Sat Oct 17 13:53:29 2015
diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst
index 4ee68b4..f8b78b6 100644
--- a/Doc/howto/logging.rst
+++ b/Doc/howto/logging.rst
@@ -134,7 +134,9 @@ interpreter, and don't just continue from the session described above::
    logging.warning('And this, too')
 
 And now if we open the file and look at what we have, we should find the log
-messages::
+messages:
+
+.. code-block:: none
 
    DEBUG:root:This message should go to the log file
    INFO:root:So should this
@@ -144,7 +146,9 @@ This example also shows how you can set the logging level which acts as the
 threshold for tracking. In this case, because we set the threshold to
 ``DEBUG``, all of the messages were printed.
 
-If you want to set the logging level from a command-line option such as::
+If you want to set the logging level from a command-line option such as:
+
+.. code-block:: none
 
    --log=INFO
 
@@ -208,7 +212,9 @@ could organize logging in it::
    def do_something():
        logging.info('Doing something')
 
-If you run *myapp.py*, you should see this in *myapp.log*::
+If you run *myapp.py*, you should see this in *myapp.log*:
+
+.. code-block:: none
 
    INFO:root:Started
    INFO:root:Doing something
@@ -258,7 +264,9 @@ specify the format you want to use::
    logging.info('So should this')
    logging.warning('And this, too')
 
-which would print::
+which would print:
+
+.. code-block:: none
 
    DEBUG:This message should appear on the console
    INFO:So should this
@@ -282,7 +290,9 @@ your format string::
    logging.basicConfig(format='%(asctime)s %(message)s')
    logging.warning('is when this event was logged.')
 
-which should print something like this::
+which should print something like this:
+
+.. code-block:: none
 
    2010-12-12 11:41:42,612 is when this event was logged.
 
@@ -294,7 +304,9 @@ argument to ``basicConfig``, as in this example::
    logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:%M:%S %p')
    logging.warning('is when this event was logged.')
 
-which would display something like this::
+which would display something like this:
+
+.. code-block:: none
 
    12/12/2010 11:46:36 AM is when this event was logged.
 
@@ -376,7 +388,9 @@ if no destination is set; and if one is not set, they will set a destination
 of the console (``sys.stderr``) and a default format for the displayed
 message before delegating to the root logger to do the actual message output.
 
-The default format set by :func:`basicConfig` for messages is::
+The default format set by :func:`basicConfig` for messages is:
+
+.. code-block:: none
 
    severity:logger name:message
 
@@ -522,7 +536,9 @@ indicator.
 .. method:: logging.Formatter.__init__(fmt=None, datefmt=None, style='%')
 
 If there is no message format string, the default is to use the
-raw message.  If there is no date format string, the default date format is::
+raw message.  If there is no date format string, the default date format is:
+
+.. code-block:: none
 
     %Y-%m-%d %H:%M:%S
 
@@ -628,7 +644,9 @@ the names of the objects::
     logger.error('error message')
     logger.critical('critical message')
 
-Here is the logging.conf file::
+Here is the logging.conf file:
+
+.. code-block:: ini
 
     [loggers]
     keys=root,simpleExample
@@ -713,7 +731,9 @@ construct the dictionary in Python code, receive it in pickled form over a
 socket, or use whatever approach makes sense for your application.
 
 Here's an example of the same configuration as above, in YAML format for
-the new dictionary-based approach::
+the new dictionary-based approach:
+
+.. code-block:: yaml
 
     version: 1
     formatters:
diff --git a/Doc/howto/regex.rst b/Doc/howto/regex.rst
index bdf687e..b09f748 100644
--- a/Doc/howto/regex.rst
+++ b/Doc/howto/regex.rst
@@ -786,7 +786,9 @@ Frequently you need to obtain more information than just whether the RE matched
 or not.  Regular expressions are often used to dissect strings by writing a RE
 divided into several subgroups which match different components of interest.
 For example, an RFC-822 header line is divided into a header name and a value,
-separated by a ``':'``, like this::
+separated by a ``':'``, like this:
+
+.. code-block:: none
 
    From: author@example.com
    User-Agent: Thunderbird 1.5.0.9 (X11/20061227)
diff --git a/Doc/howto/unicode.rst b/Doc/howto/unicode.rst
index 093f445..be1fefb 100644
--- a/Doc/howto/unicode.rst
+++ b/Doc/howto/unicode.rst
@@ -30,7 +30,9 @@ spellings such as 'coöperate'.)
 
 For a while people just wrote programs that didn't display accents.
 In the mid-1980s an Apple II BASIC program written by a French speaker
-might have lines like these::
+might have lines like these:
+
+.. code-block:: basic
 
    PRINT "MISE A JOUR TERMINEE"
    PRINT "PARAMETRES ENREGISTRES"
diff --git a/Doc/howto/urllib2.rst b/Doc/howto/urllib2.rst
index c1fd5cf..204a05a 100644
--- a/Doc/howto/urllib2.rst
+++ b/Doc/howto/urllib2.rst
@@ -457,7 +457,9 @@ error code) requesting authentication.  This specifies the authentication scheme
 and a 'realm'. The header looks like: ``WWW-Authenticate: SCHEME
 realm="REALM"``.
 
-e.g. ::
+e.g.
+
+.. code-block:: none
 
     WWW-Authenticate: Basic realm="cPanel Users"