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

29 files changed, 301 insertions, 137 deletions

diff --git a/Doc/distutils/configfile.rst b/Doc/distutils/configfile.rst
index 21f1acdace..cd10a7fdf3 100644
--- a/Doc/distutils/configfile.rst
+++ b/Doc/distutils/configfile.rst
@@ -36,7 +36,9 @@ consequences:
 * installers can override anything in :file:`setup.cfg` using the command-line
   options to :file:`setup.py`
 
-The basic syntax of the configuration file is simple::
+The basic syntax of the configuration file is simple:
+
+.. code-block:: ini
 
    [command]
    option=value
@@ -51,9 +53,11 @@ option values can be split across multiple lines simply by indenting the
 continuation lines.
 
 You can find out the list of options supported by a particular command with the
-universal :option:`!--help` option, e.g. ::
+universal :option:`!--help` option, e.g.
+
+.. code-block:: shell-session
 
-   > python setup.py --help build_ext
+   $ python setup.py --help build_ext
    [...]
    Options for 'build_ext' command:
      --build-lib (-b)     directory for compiled extension modules
@@ -75,14 +79,18 @@ For example, say you want your extensions to be built "in-place"---that is, you
 have an extension :mod:`pkg.ext`, and you want the compiled extension file
 (:file:`ext.so` on Unix, say) to be put in the same source directory as your
 pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`.  You can always use the
-:option:`!--inplace` option on the command-line to ensure this::
+:option:`!--inplace` option on the command-line to ensure this:
+
+.. code-block:: sh
 
    python setup.py build_ext --inplace
 
 But this requires that you always specify the :command:`build_ext` command
 explicitly, and remember to provide :option:`!--inplace`. An easier way is to
 "set and forget" this option, by encoding it in :file:`setup.cfg`, the
-configuration file for this distribution::
+configuration file for this distribution:
+
+.. code-block:: ini
 
    [build_ext]
    inplace=1
@@ -103,7 +111,9 @@ information comes from the setup script, and some is automatically generated by
 the Distutils (such as the list of files installed).  But some of it has to be
 supplied as options to :command:`bdist_rpm`, which would be very tedious to do
 on the command-line for every run.  Hence, here is a snippet from the Distutils'
-own :file:`setup.cfg`::
+own :file:`setup.cfg`:
+
+.. code-block:: ini
 
    [bdist_rpm]
    release = 1
diff --git a/Doc/distutils/packageindex.rst b/Doc/distutils/packageindex.rst
index 44556e3df9..086e14eb25 100644
--- a/Doc/distutils/packageindex.rst
+++ b/Doc/distutils/packageindex.rst
@@ -156,7 +156,9 @@ The :command:`register` and :command:`upload` commands both check for the
 existence of a :file:`.pypirc` file at the location :file:`$HOME/.pypirc`.
 If this file exists, the command uses the username, password, and repository
 URL configured in the file.  The format of a :file:`.pypirc` file is as
-follows::
+follows:
+
+.. code-block:: ini
 
     [distutils]
     index-servers =
@@ -179,7 +181,9 @@ Each section describing a repository defines three variables:
     will be prompt to type it when needed.
 
 If you want to define another server a new section can be created and
-listed in the *index-servers* variable::
+listed in the *index-servers* variable:
+
+.. code-block:: ini
 
     [distutils]
     index-servers =
diff --git a/Doc/extending/embedding.rst b/Doc/extending/embedding.rst
index ab2f61614a..7e4fc19db8 100644
--- a/Doc/extending/embedding.rst
+++ b/Doc/extending/embedding.rst
@@ -323,7 +323,7 @@ options.  In this case, the :mod:`sysconfig` module is a useful tool to
 programmatically extract the configuration values that you will want to
 combine together.  For example:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> import sysconfig
    >>> sysconfig.get_config_var('LIBS')
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index e02f7837b6..82b689e064 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -43,7 +43,9 @@ Let's create an extension module called ``spam`` (the favorite food of Monty
 Python fans...) and let's say we want to create a Python interface to the C
 library function :c:func:`system` [#]_. This function takes a null-terminated
 character string as argument and returns an integer.  We want this function to
-be callable from Python as follows::
+be callable from Python as follows:
+
+.. code-block:: pycon
 
    >>> import spam
    >>> status = spam.system("ls -l")
@@ -439,7 +441,9 @@ part of the Python interpreter, you will have to change the configuration setup
 and rebuild the interpreter.  Luckily, this is very simple on Unix: just place
 your file (:file:`spammodule.c` for example) in the :file:`Modules/` directory
 of an unpacked source distribution, add a line to the file
-:file:`Modules/Setup.local` describing your file::
+:file:`Modules/Setup.local` describing your file:
+
+.. code-block:: sh
 
    spam spammodule.o
 
@@ -450,7 +454,9 @@ subdirectory, but then you must first rebuild :file:`Makefile` there by running
 :file:`Setup` file.)
 
 If your module requires additional libraries to link with, these can be listed
-on the line in the configuration file as well, for instance::
+on the line in the configuration file as well, for instance:
+
+.. code-block:: sh
 
    spam spammodule.o -lX11
 
diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst
index 5e05cf6936..ac48637bbe 100644
--- a/Doc/extending/newtypes_tutorial.rst
+++ b/Doc/extending/newtypes_tutorial.rst
@@ -117,7 +117,7 @@ field mentioned above. ::
 The name of our type.  This will appear in the default textual representation of
 our objects and in some error messages, for example:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> "" + custom.Custom()
    Traceback (most recent call last):
@@ -183,7 +183,7 @@ set to *NULL*. ::
 This adds the type to the module dictionary.  This allows us to create
 :class:`Custom` instances by calling the :class:`Custom` class:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> import custom
    >>> mycustom = custom.Custom()
@@ -655,7 +655,7 @@ Python has a :term:`cyclic garbage collector (GC) <garbage collection>` that
 can identify unneeded objects even when their reference counts are not zero.
 This can happen when objects are involved in cycles.  For example, consider:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> l = []
    >>> l.append(l)
@@ -672,7 +672,7 @@ Besides, in the second and third versions, we allowed subclassing
 :class:`Custom`, and subclasses may add arbitrary attributes.  For any of
 those two reasons, :class:`Custom` objects can participate in cycles:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> import custom3
    >>> class Derived(custom3.Custom): pass
@@ -796,7 +796,7 @@ built-in :class:`list` type. The new type will be completely compatible with
 regular lists, but will have an additional :meth:`increment` method that
 increases an internal counter:
 
-.. code-block:: python
+.. code-block:: pycon
 
    >>> import sublist
    >>> s = sublist.SubList(range(3))
diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst
index f84feadd78..aec4bf9b85 100644
--- a/Doc/faq/library.rst
+++ b/Doc/faq/library.rst
@@ -74,7 +74,9 @@ interpreter.
 
 Occasionally, a user's environment is so full that the :program:`/usr/bin/env`
 program fails; or there's no env program at all.  In that case, you can try the
-following hack (due to Alex Rezinsky)::
+following hack (due to Alex Rezinsky):
+
+.. code-block:: sh
 
    #! /bin/sh
    """:"
diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst
index f049bc8387..7792cfaa16 100644
--- a/Doc/faq/windows.rst
+++ b/Doc/faq/windows.rst
@@ -1,5 +1,7 @@
 :tocdepth: 2
 
+.. highlightlang:: none
+
 .. _windows-faq:
 
 =====================
@@ -39,12 +41,16 @@ or "Command prompt window".  Usually you can create such a window from your
 Start menu; under Windows 7 the menu selection is :menuselection:`Start -->
 Programs --> Accessories --> Command Prompt`.  You should be able to recognize
 when you have started such a window because you will see a Windows "command
-prompt", which usually looks like this::
+prompt", which usually looks like this:
+
+.. code-block:: doscon
 
    C:\>
 
 The letter may be different, and there might be other things after it, so you
-might just as easily see something like::
+might just as easily see something like:
+
+.. code-block:: doscon
 
    D:\YourName\Projects\Python>
 
@@ -60,11 +66,15 @@ program. So, how do you arrange for the interpreter to handle your Python?
 First, you need to make sure that your command window recognises the word
 "python" as an instruction to start the interpreter.  If you have opened a
 command window, you should try entering the command ``python`` and hitting
-return::
+return:
+
+.. code-block:: doscon
 
    C:\Users\YourName> python
 
-You should then see something like::
+You should then see something like:
+
+.. code-block:: pycon
 
    Python 3.3.0 (v3.3.0:bd8afb90ebf2, Sep 29 2012, 10:55:48) [MSC v.1600 32 bit (Intel)] on win32
    Type "help", "copyright", "credits" or "license" for more information.
@@ -73,7 +83,9 @@ You should then see something like::
 You have started the interpreter in "interactive mode". That means you can enter
 Python statements or expressions interactively and have them executed or
 evaluated while you wait.  This is one of Python's strongest features.  Check it
-by entering a few expressions of your choice and seeing the results::
+by entering a few expressions of your choice and seeing the results:
+
+.. code-block:: pycon
 
     >>> print("Hello")
     Hello
@@ -317,7 +329,9 @@ present, and ``getch()`` which gets one character without echoing it.
 How do I emulate os.kill() in Windows?
 --------------------------------------
 
-Prior to Python 2.7 and 3.2, to terminate a process, you can use :mod:`ctypes`::
+Prior to Python 2.7 and 3.2, to terminate a process, you can use :mod:`ctypes`:
+
+.. code-block:: python
 
    import ctypes
 
diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst
index 9d770f5232..e78a022b37 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 d3c7d66895..788a0eee2b 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 b9c51a4a45..b63c43c81f 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 4d2d052d29..fdf7874883 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 4ee68b4747..f8b78b6185 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 bdf687ee45..b09f748a92 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 093f4454af..be1fefb35a 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 c1fd5cf068..204a05a610 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"
 
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index 0545b8f33d..92cdf2f114 100644
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -283,7 +283,9 @@ Windows, choose :menuselection:`Start --> Programs --> Python X.Y -->
 Python (command line)`.   Once the interpreter is started, you type Python code
 at the prompt.  For example, on my Linux system, I type the three Python
 statements shown below, and get the output as shown, to find out my
-:file:`{prefix}` and :file:`{exec-prefix}`::
+:file:`{prefix}` and :file:`{exec-prefix}`:
+
+.. code-block:: pycon
 
    Python 2.4 (#26, Aug  7 2004, 17:19:02)
    Type "help", "copyright", "credits" or "license" for more information.
@@ -622,7 +624,9 @@ parsing your configuration file(s).
 
 Obviously, specifying the entire installation scheme every time you install a
 new module distribution would be very tedious.  Thus, you can put these options
-into your Distutils config file (see section :ref:`inst-config-files`)::
+into your Distutils config file (see section :ref:`inst-config-files`):
+
+.. code-block:: ini
 
    [install]
    install-base=$HOME
@@ -631,7 +635,9 @@ into your Distutils config file (see section :ref:`inst-config-files`)::
    install-scripts=python/scripts
    install-data=python/data
 
-or, equivalently, ::
+or, equivalently,
+
+.. code-block:: ini
 
    [install]
    install-base=$HOME/python
@@ -718,7 +724,9 @@ A slightly less convenient way is to edit the :file:`site.py` file in Python's
 standard library, and modify ``sys.path``.  :file:`site.py` is automatically
 imported when the Python interpreter is executed, unless the :option:`-S` switch
 is supplied to suppress this behaviour.  So you could simply edit
-:file:`site.py` and add two lines to it::
+:file:`site.py` and add two lines to it:
+
+.. code-block:: python
 
    import sys
    sys.path.append('/www/python/')
@@ -839,7 +847,9 @@ plus a ``global`` section for global options that affect every command.  Each
 section consists of one option per line, specified as ``option=value``.
 
 For example, the following is a complete config file that just forces all
-commands to run quietly by default::
+commands to run quietly by default:
+
+.. code-block:: ini
 
    [global]
    verbose=0
@@ -853,7 +863,9 @@ distribution.
 
 You could override the default "build base" directory and make the
 :command:`build\*` commands always forcibly rebuild all files with the
-following::
+following:
+
+.. code-block:: ini
 
    [build]
    build-base=blib
diff --git a/Doc/library/faulthandler.rst b/Doc/library/faulthandler.rst
index d0c4cd07c5..94ebd87639 100644
--- a/Doc/library/faulthandler.rst
+++ b/Doc/library/faulthandler.rst
@@ -152,10 +152,10 @@ these functions again each time that the file is replaced.
 Example
 -------
 
-.. highlight:: sh
-
 Example of a segmentation fault on Linux with and without enabling the fault
-handler::
+handler:
+
+.. code-block:: shell-session
 
     $ python3 -c "import ctypes; ctypes.string_at(0)"
     Segmentation fault
diff --git a/Doc/library/json.rst b/Doc/library/json.rst
index bcad61aeca..85798fa2cf 100644
--- a/Doc/library/json.rst
+++ b/Doc/library/json.rst
@@ -100,9 +100,9 @@ Extending :class:`JSONEncoder`::
     ['[2.0', ', 1.0', ']']
 
 
-.. highlight:: bash
+Using :mod:`json.tool` from the shell to validate and pretty-print:
 
-Using :mod:`json.tool` from the shell to validate and pretty-print::
+.. code-block:: shell-session
 
     $ echo '{"json":"obj"}' | python -m json.tool
     {
@@ -113,8 +113,6 @@ Using :mod:`json.tool` from the shell to validate and pretty-print::
 
 See :ref:`json-commandline` for detailed documentation.
 
-.. highlight:: python3
-
 .. note::
 
    JSON is a subset of `YAML <http://yaml.org/>`_ 1.2.  The JSON produced by
@@ -647,8 +645,6 @@ when serializing Python :class:`int` values of extremely large magnitude, or
 when serializing instances of "exotic" numerical types such as
 :class:`decimal.Decimal`.
 
-.. highlight:: bash
-
 .. _json-commandline:
 
 Command Line Interface
@@ -665,7 +661,9 @@ The :mod:`json.tool` module provides a simple command line interface to validate
 and pretty-print JSON objects.
 
 If the optional ``infile`` and ``outfile`` arguments are not
-specified, :attr:`sys.stdin` and :attr:`sys.stdout` will be used respectively::
+specified, :attr:`sys.stdin` and :attr:`sys.stdout` will be used respectively:
+
+.. code-block:: shell-session
 
     $ echo '{"json": "obj"}' | python -m json.tool
     {
@@ -684,7 +682,9 @@ Command line options
 
 .. cmdoption:: infile
 
-   The JSON file to be validated or pretty-printed::
+   The JSON file to be validated or pretty-printed:
+
+   .. code-block:: shell-session
 
       $ python -m json.tool mp_films.json
       [
diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst
index 06378379c3..1f9d7c7f22 100644
--- a/Doc/library/logging.config.rst
+++ b/Doc/library/logging.config.rst
@@ -538,7 +538,9 @@ target handler, and the system will resolve to the handler from the
 id.  If, however, a user defines a ``my.package.MyHandler`` which has
 an ``alternate`` handler, the configuration system would not know that
 the ``alternate`` referred to a handler.  To cater for this, a generic
-resolution system allows the user to specify::
+resolution system allows the user to specify:
+
+.. code-block:: yaml
 
     handlers:
       file:
@@ -552,7 +554,9 @@ The literal string ``'cfg://handlers.file'`` will be resolved in an
 analogous way to strings with the ``ext://`` prefix, but looking
 in the configuration itself rather than the import namespace.  The
 mechanism allows access by dot or by index, in a similar way to
-that provided by ``str.format``.  Thus, given the following snippet::
+that provided by ``str.format``.  Thus, given the following snippet:
+
+.. code-block:: yaml
 
     handlers:
       email:
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 88f804a074..f9eda173ad 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -179,7 +179,9 @@ is the module's name in the Python package namespace.
 
       You can specify *stack_info* independently of *exc_info*, e.g. to just show
       how you got to a certain point in your code, even when no exceptions were
-      raised. The stack frames are printed following a header line which says::
+      raised. The stack frames are printed following a header line which says:
+
+      .. code-block:: none
 
           Stack (most recent call last):
 
@@ -198,7 +200,9 @@ is the module's name in the Python package namespace.
          logger = logging.getLogger('tcpserver')
          logger.warning('Protocol problem: %s', 'connection reset', extra=d)
 
-      would print something like  ::
+      would print something like
+
+      .. code-block:: none
 
          2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset
 
@@ -939,7 +943,9 @@ functions.
 
    You can specify *stack_info* independently of *exc_info*, e.g. to just show
    how you got to a certain point in your code, even when no exceptions were
-   raised. The stack frames are printed following a header line which says::
+   raised. The stack frames are printed following a header line which says:
+
+   .. code-block:: none
 
        Stack (most recent call last):
 
@@ -957,7 +963,9 @@ functions.
       d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
       logging.warning('Protocol problem: %s', 'connection reset', extra=d)
 
-   would print something like::
+   would print something like:
+
+   .. code-block:: none
 
       2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset
 
diff --git a/Doc/library/site.rst b/Doc/library/site.rst
index ae408133a7..0003a7cd8f 100644
--- a/Doc/library/site.rst
+++ b/Doc/library/site.rst
@@ -222,7 +222,7 @@ Module contents
 The :mod:`site` module also provides a way to get the user directories from the
 command line:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 -m site --user-site
    /home/user/.local/lib/python3.3/site-packages
diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst
index 8bbadf1160..d922fd6f32 100644
--- a/Doc/library/timeit.rst
+++ b/Doc/library/timeit.rst
@@ -25,7 +25,7 @@ Basic Examples
 The following example shows how the :ref:`timeit-command-line-interface`
 can be used to compare three different expressions:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python3 -m timeit '"-".join(str(n) for n in range(100))'
    10000 loops, best of 5: 30.2 usec per loop
@@ -264,7 +264,7 @@ Examples
 
 It is possible to provide a setup statement that is executed only once at the beginning:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python -m timeit -s 'text = "sample string"; char = "g"'  'char in text'
    5000000 loops, best of 5: 0.0877 usec per loop
@@ -293,7 +293,7 @@ The following examples show how to time expressions that contain multiple lines.
 Here we compare the cost of using :func:`hasattr` vs. :keyword:`try`/:keyword:`except`
 to test for missing and present object attributes:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python -m timeit 'try:' '  str.__bool__' 'except AttributeError:' '  pass'
    20000 loops, best of 5: 15.7 usec per loop
diff --git a/Doc/library/tokenize.rst b/Doc/library/tokenize.rst
index 02a0428f21..4c0a0ceef7 100644
--- a/Doc/library/tokenize.rst
+++ b/Doc/library/tokenize.rst
@@ -218,7 +218,7 @@ will be tokenized to the following output where the first column is the range
 of the line/column coordinates where the token is found, the second column is
 the name of the token, and the final column is the value of the token (if any)
 
-.. code-block:: sh
+.. code-block:: shell-session
 
     $ python -m tokenize hello.py
     0,0-0,0:            ENCODING       'utf-8'
@@ -244,7 +244,7 @@ the name of the token, and the final column is the value of the token (if any)
 
 The exact token type names can be displayed using the :option:`-e` option:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
     $ python -m tokenize -e hello.py
     0,0-0,0:            ENCODING       'utf-8'
diff --git a/Doc/library/zipapp.rst b/Doc/library/zipapp.rst
index a9a61c969c..26b0f19fde 100644
--- a/Doc/library/zipapp.rst
+++ b/Doc/library/zipapp.rst
@@ -27,7 +27,7 @@ can be used to create an executable archive from a directory containing
 Python code.  When run, the archive will execute the ``main`` function from
 the module ``myapp`` in the archive.
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python -m zipapp myapp -m "myapp:main"
    $ python myapp.pyz
@@ -41,7 +41,7 @@ Command-Line Interface
 
 When called as a program from the command line, the following form is used:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python -m zipapp source [options]
 
@@ -189,7 +189,7 @@ Examples
 
 Pack up a directory into an archive, and run it.
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python -m zipapp myapp
    $ python myapp.pyz
@@ -203,7 +203,7 @@ The same can be done using the :func:`create_archive` functon::
 To make the application directly executable on POSIX, specify an interpreter
 to use.
 
-.. code-block:: sh
+.. code-block:: shell-session
 
    $ python -m zipapp myapp -p "/usr/bin/env python"
    $ ./myapp.pyz
@@ -273,7 +273,7 @@ The steps to create a standalone archive are as follows:
 2. Install all of your application's dependencies into the ``myapp`` directory,
    using pip:
 
-   .. code-block:: sh
+   .. code-block:: shell-session
 
       $ python -m pip install -r requirements.txt --target myapp
 
@@ -288,7 +288,7 @@ The steps to create a standalone archive are as follows:
 
 4. Package the application using:
 
-   .. code-block:: sh
+   .. code-block:: shell-session
 
       $ python -m zipapp -p "interpreter" myapp
 
diff --git a/Doc/tutorial/appendix.rst b/Doc/tutorial/appendix.rst
index ffd16aa97a..241a812037 100644
--- a/Doc/tutorial/appendix.rst
+++ b/Doc/tutorial/appendix.rst
@@ -52,7 +52,7 @@ comment in Python.
 The script can be given an executable mode, or permission, using the
 :program:`chmod` command.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
    $ chmod +x myscript.py
 
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 21ba0b5ceb..e72dea9075 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -178,11 +178,15 @@ Generic options
 .. cmdoption:: -V
                --version
 
-   Print the Python version number and exit.  Example output could be::
+   Print the Python version number and exit.  Example output could be:
+
+   .. code-block:: none
 
        Python 3.6.0b2+
 
-   When given twice, print more information about the build, like::
+   When given twice, print more information about the build, like:
+
+   .. code-block:: none
 
        Python 3.6.0b2+ (3.6:84a3c5003510+, Oct 26 2016, 02:33:55)
        [GCC 6.2.0 20161005]
@@ -355,7 +359,9 @@ Miscellaneous options
 
    Warning control.  Python's warning machinery by default prints warning
    messages to :data:`sys.stderr`.  A typical warning message has the following
-   form::
+   form:
+
+   .. code-block:: none
 
        file:line: category: message
 
diff --git a/Doc/using/unix.rst b/Doc/using/unix.rst
index ac99b69986..8b392f8a56 100644
--- a/Doc/using/unix.rst
+++ b/Doc/using/unix.rst
@@ -118,7 +118,9 @@ Miscellaneous
 =============
 
 To easily use Python scripts on Unix, you need to make them executable,
-e.g. with ::
+e.g. with
+
+.. code-block:: shell-session
 
    $ chmod +x script
 
diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst
index 47d423f42d..3bab6fe503 100644
--- a/Doc/using/windows.rst
+++ b/Doc/using/windows.rst
@@ -210,7 +210,9 @@ The options listed above can also be provided in a file named ``unattend.xml``
 alongside the executable. This file specifies a list of options and values.
 When a value is provided as an attribute, it will be converted to a number if
 possible. Values provided as element text are always left as strings. This
-example file sets the same options and the previous example::
+example file sets the same options and the previous example:
+
+.. code-block:: xml
 
     <Options>
         <Option Name="InstallAllUsers" Value="no" />
@@ -343,7 +345,9 @@ Windows allows environment variables to be configured permanently at both the
 User level and the System level, or temporarily in a command prompt.
 
 To temporarily set environment variables, open Command Prompt and use the
-:command:`set` command::
+:command:`set` command:
+
+.. code-block:: doscon
 
     C:\>set PATH=C:\Program Files\Python 3.6;%PATH%
     C:\>set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
@@ -503,7 +507,7 @@ From a script
 Let's create a test Python script - create a file called ``hello.py`` with the
 following contents
 
-::
+.. code-block:: python
 
     #! python
     import sys
@@ -518,7 +522,7 @@ From the directory in which hello.py lives, execute the command:
 You should notice the version number of your latest Python 2.x installation
 is printed.  Now try changing the first line to be:
 
-::
+.. code-block:: python
 
     #! python3
 
@@ -566,7 +570,7 @@ which interpreter to use.  The supported virtual commands are:
 
 For example, if the first line of your script starts with
 
-::
+.. code-block:: sh
 
   #! /usr/bin/python
 
@@ -592,7 +596,7 @@ Arguments in shebang lines
 The shebang lines can also specify additional options to be passed to the
 Python interpreter.  For example, if you have a shebang line:
 
-::
+.. code-block:: sh
 
   #! /usr/bin/python -v
 
@@ -683,7 +687,7 @@ For example:
 
 * Setting ``PY_PYTHON=3.1`` is equivalent to the INI file containing:
 
-::
+.. code-block:: ini
 
   [defaults]
   python=3.1
@@ -691,7 +695,7 @@ For example:
 * Setting ``PY_PYTHON=3`` and ``PY_PYTHON3=3.1`` is equivalent to the INI file
   containing:
 
-::
+.. code-block:: ini
 
   [defaults]
   python=3
diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst
index a355af7adb..f7fe70fa94 100644
--- a/Doc/whatsnew/3.6.rst
+++ b/Doc/whatsnew/3.6.rst
@@ -2196,7 +2196,9 @@ Changes in the Python API
   platform-specific selection is made.
   In environments where distributions are
   built on Windows and zip distributions are required, configure
-  the project with a ``setup.cfg`` file containing the following::
+  the project with a ``setup.cfg`` file containing the following:
+
+  .. code-block:: ini
 
     [sdist]
     formats=zip