Use an appropriate highlight language throughout (#283)

* Use an appropriate highlight language throughout.

Replace the default (Python) highlighting where a Pygments lexer is
available, and use "none" elsewhere. For console commands follow the
example of gitbootcamp.rst mostly ($-prompt and lang=console).

* Document the highlight directive correctly.

* Remove spurious prompt from quoted output.

* Respect the author's decision to use $ (or not) in console text.

Where the $-prompt is explicit, highlight as console, and where implicit
as bash (mostly).

Author: jeff5

buildbots.rst

@@ -3,6 +3,8 @@
 Continuous Integration
 ======================
 
+.. highlight:: bash
+
 To assert that there are no regressions in the :doc:`development and maintenance
 branches <devcycle>`, Python has a set of dedicated machines (called *buildbots*
 or *build slaves*) used for continuous integration.  They span a number of
@@ -107,7 +109,10 @@ The ``--randseed`` option makes it easy to reproduce the exact randomization
 used in a given build.  Again, open the ``stdio`` link for the failing test
 run, and check the beginning of the test output proper.
 
-Let's assume, for the sake of example, that the output starts with::
+Let's assume, for the sake of example, that the output starts with:
+
+.. code-block:: none
+   :emphasize-lines: 6
 
    ./python -Wd -E -bb Lib/test/regrtest.py -uall -rwW
    == CPython 3.3a0 (default:22ae2b002865, Mar 30 2011, 13:58:40) [GCC 4.4.5]
@@ -122,7 +127,9 @@ You can reproduce the exact same order using::
 
    ./python -Wd -E -bb -m test -uall -rwW --randseed 2613169
 
-It will run the following sequence (trimmed for brevity)::
+It will run the following sequence (trimmed for brevity):
+
+.. code-block:: none
 
    [  1/353] test_augassign
    [  2/353] test_functools
@@ -140,15 +147,19 @@ sequence recorded in that text file::
    ./python -Wd -E -bb -m test -uall -rwW --fromfile mytestsequence.txt
 
 In the example sequence above, if ``test_unicode`` had failed, you would
-first test the following sequence::
+first test the following sequence:
+
+.. code-block:: none
 
    [  1/353] test_augassign
    [  2/353] test_functools
    [  3/353] test_bool
    [  6/353] test_unicode
 
 And, if it succeeds, the following one instead (which, hopefully, shall
-fail)::
+fail):
+
+.. code-block:: none
 
    [  4/353] test_contains
    [  5/353] test_compileall
@@ -193,6 +204,8 @@ implementation, or by making its parameters - such as a timeout - more robust.
 Custom builders
 ---------------
 
+.. highlight:: console
+
 When working on a platform-specific issue, you may want to test your changes on
 the buildbot fleet rather than just on Travis and AppVeyor.  To do so, you can
 make use of the `custom builders

buildslave.rst

@@ -4,6 +4,8 @@
 Running a buildslave
 ====================
 
+.. highlight:: bash
+
 Python's :ref:`buildbots` system was discussed earlier.  We sometimes refer to
 the collection of *build slaves* as our "buildbot fleet".  The machines that
 comprise the fleet are voluntarily contributed resources.  Many are run by
@@ -135,7 +137,9 @@ For OSX:
       If you use pip with Apple's system python, add '/System' to the front of
       the path to the Python bin directory.
 
-    * Place a file with the following contents into ``/Library/LaunchDaemons``::
+   *  Place a file with the following contents into ``/Library/LaunchDaemons``:
+
+      .. code-block:: xml
 
           <?xml version="1.0" encoding="UTF-8"?>
           <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"

clang.rst

@@ -2,6 +2,8 @@
 Dynamic Analysis with Clang
 ***************************
 
+.. highlight:: bash
+
 This document describes how to use Clang to perform analysis on Python and its
 libraries. In addition to performing the analysis, the document will cover
 downloading, building and installing the the latest Clang/LLVM combination
@@ -95,7 +97,9 @@ Perform the following to download, build and install the Clang/LLVM 3.4. ::
 
 After ``make install`` executes, the compilers will be installed in
 ``/usr/local/bin`` and the various libraries will be installed in
-``/usr/local/lib/clang/3.4/lib/linux/``: ::
+``/usr/local/lib/clang/3.4/lib/linux/``:
+
+.. code-block:: console
 
     $ ls /usr/local/lib/clang/3.4/lib/linux/
     libclang_rt.asan-x86_64.a   libclang_rt.profile-x86_64.a
@@ -105,7 +109,9 @@ After ``make install`` executes, the compilers will be installed in
     libclang_rt.msan-x86_64.a   libclang_rt.ubsan-x86_64.a
 
 On Mac OS X, the libraries are installed in
-``/usr/local/lib/clang/3.3/lib/darwin/``: ::
+``/usr/local/lib/clang/3.3/lib/darwin/``:
+
+.. code-block:: console
 
     $ ls /usr/local/lib/clang/3.3/lib/darwin/
     libclang_rt.10.4.a                    libclang_rt.ios.a
@@ -181,7 +187,9 @@ The ``-fno-sanitize=vptr`` removes vtable checks that are part of UBSan from C++
 projects due to noise. Its not needed with Python, but you will likely need it
 for other C++ projects.
 
-After exporting ``CC`` and ``CXX``, ``configure`` as normal: ::
+After exporting ``CC`` and ``CXX``, ``configure`` as normal:
+
+.. code-block:: console
 
     $ ./configure
     checking build system type... x86_64-unknown-linux-gnu
@@ -194,7 +202,9 @@ After exporting ``CC`` and ``CXX``, ``configure`` as normal: ::
     checking whether the C compiler works... yes
     ...
 
-Next is a standard ``make`` (formatting added for clarity): ::
+Next is a standard ``make`` (formatting added for clarity):
+
+.. code-block:: console
 
     $ make
     /usr/local/bin/clang -fsanitize=undefined -c -Wno-unused-result
@@ -207,7 +217,9 @@ Next is a standard ``make`` (formatting added for clarity): ::
         Parser/acceler.c
     ...
 
-Finally is ``make test`` (formatting added for clarity): ::
+Finally is ``make test`` (formatting added for clarity):
+
+.. code-block:: none
 
     Objects/longobject.c:39:42: runtime error: index -1 out of bounds
         for type 'PyLongObject [262]'
@@ -221,7 +233,9 @@ Finally is ``make test`` (formatting added for clarity): ::
 
 If you are using the address sanitizer, its important to pipe the output through
 ``asan_symbolize.py`` to get a good trace. For example, from Issue 20953 during
-compile (formatting added for clarity): ::
+compile (formatting added for clarity):
+
+.. code-block:: none
 
     $ make test 2>&1 | asan_symbolize.py
     ...
@@ -293,22 +307,24 @@ compile (formatting added for clarity): ::
 Blacklisting (Ignoring) Findings
 --------------------------------
 
+.. highlight:: none
+
 Clang allows you to alter the behavior of sanitizer tools for certain
 source-level by providing a special blacklist file at compile-time. The
 blacklist is needed because it reports every instance of an issue, even if the
 issue is reported 10's of thousands of time in un-managed library code.
 
-You specify the blacklist with ``-fsanitize-blacklist=XXX``. For example: ::
+You specify the blacklist with ``-fsanitize-blacklist=XXX``. For example::
 
     -fsanitize-blacklist=my_blacklist.txt
 
 ``my_blacklist.txt`` would then contain entries such as the following. The entry
-will ignore a bug in ``libc++``'s ``ios`` formatting functions: ::
+will ignore a bug in ``libc++``'s ``ios`` formatting functions::
 
     fun:_Ios_Fmtflags
 
 As an example with Python 3.4.0, ``audioop.c`` will produce a number of
-findings: ::
+findings::
 
     ./Modules/audioop.c:422:11: runtime error: left shift of negative value -1
     ./Modules/audioop.c:446:19: runtime error: left shift of negative value -1
@@ -324,11 +340,11 @@ findings: ::
     ...
 
 One of the function of interest is ``audioop_getsample_impl`` (flagged at line
-422), and the blacklist entry would include: ::
+422), and the blacklist entry would include::
 
     fun:audioop_getsample_imp
 
-Or, you could ignore the entire file with: ::
+Or, you could ignore the entire file with::
 
     src:Modules/audioop.c
 

committing.rst

@@ -3,6 +3,8 @@
 Accepting Pull Requests
 =======================
 
+.. highlight:: none
+
 This page is aimed to core developers, and covers the steps required to
 accept, merge, and possibly backport a pull request on the main repository.
 

compiler.rst

@@ -3,6 +3,7 @@
 Design of CPython's Compiler
 ============================
 
+.. highlight:: none
 
 Abstract
 --------
@@ -55,9 +56,10 @@ macros (which are all defined in :file:`Include/node.h`):
         retrieve the line number of the source code that led to the
         creation of the parse rule; defined in :file:`Python/ast.c`
 
-For example, consider the rule for 'while'::
+For example, consider the rule for 'while':
 
-  while_stmt: 'while' test ':' suite ['else' ':' suite]
+.. productionlist::
+   while_stmt: "while" `expression` ":" `suite` : ["else" ":" `suite`]
 
 The node representing this will have ``TYPE(node) == while_stmt`` and
 the number of children can be 4 or 7 depending on whether there is an
@@ -93,13 +95,13 @@ particular programming language.
 The following fragment of the Python ASDL construct demonstrates the
 approach and syntax::
 
-  module Python
-  {
-        stmt = FunctionDef(identifier name, arguments args, stmt* body,
-                            expr* decorators)
+   module Python
+   {
+       stmt = FunctionDef(identifier name, arguments args, stmt* body,
+                          expr* decorators)
               | Return(expr? value) | Yield(expr? value)
               attributes (int lineno)
-  }
+   }
 
 The preceding example describes two different kinds of statements and an
 expression: function definitions, return statements, and yield expressions.

docquality.rst

@@ -70,7 +70,7 @@ that makes it harder to break the work up for multiple people to help with.
 Helping with the Developer's Guide
 ----------------------------------
 
-.. highlight:: bash
+.. highlight:: console
 
 The Developer's Guide uses the same process as the main Python documentation,
 except for some small differences.  The source lives in a `separate
@@ -90,13 +90,13 @@ Python projects is to create a virtualenv, and then install dependencies from
 a ``requirements.txt`` file. For your convenience, this is all *automated for
 you*. To build the devguide on a Unix-like system use::
 
-    $ make html
+   $ make html
 
 in the checkout directory. On Windows use:
 
-..  code-block:: doscon
+.. code-block:: doscon
 
-    > .\make html
+   > .\make html
 
 You will find the generated files in ``_build/html``.
 Note that ``make check`` is automatically run when

documenting.rst

@@ -4,6 +4,8 @@
 Documenting Python
 ==================
 
+.. highlight::  rest
+
 The Python language has a substantial body of documentation, much of it
 contributed by various authors. The markup used for the Python documentation is
 `reStructuredText`_, developed by the `docutils`_ project, amended by custom
@@ -810,27 +812,29 @@ preceding paragraph and delimited by indentation.
 Representing an interactive session requires including the prompts and output
 along with the Python code.  No special markup is required for interactive
 sessions.  After the last line of input or output presented, there should not be
-an "unused" primary prompt; this is an example of what *not* to do::
+an "unused" primary prompt; this is an example of what *not* to do:
+
+.. code-block:: python
 
    >>> 1 + 1
    2
    >>>
 
 Syntax highlighting is handled in a smart way:
 
-* There is a "highlighting language" for each source file.  Per default,
+* There is a "highlighting language" for each source file.  By default,
   this is ``'python'`` as the majority of files will have to highlight Python
   snippets.
 
 * Within Python highlighting mode, interactive sessions are recognized
   automatically and highlighted appropriately.
 
-* The highlighting language can be changed using the ``highlightlang``
+* The highlighting language can be changed using the ``highlight``
   directive, used as follows::
 
-     .. highlightlang:: c
+     .. highlight:: c
 
-  This language is used until the next ``highlightlang`` directive is
+  This language is used until the next ``highlight`` directive is
   encountered.
 
 * The ``code-block`` directive can be used to specify the highlight language
@@ -1035,7 +1039,7 @@ in a different style:
    The name of a file or directory.  Within the contents, you can use curly
    braces to indicate a "variable" part, for example::
 
-      ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
+      ``spam`` is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
 
    In the built documentation, the ``x`` will be displayed differently to
    indicate that it is to be replaced by the Python minor version.
@@ -1452,6 +1456,8 @@ default. They are set in the build configuration file :file:`conf.py`.
 Building the documentation
 ==========================
 
+.. highlight:: bash
+
 The toolset used to build the docs is written in Python and is called Sphinx_.
 Sphinx is maintained separately and is not included in this tree.  Also needed
 are docutils_, supplying the base markup that Sphinx uses; Jinja_, a templating

gdb.rst

@@ -3,6 +3,8 @@
 gdb Support
 ===========
 
+.. highlight:: none
+
 If you experience low-level problems such as crashes or deadlocks
 (e.g. when tinkering with parts of CPython which are written in C),
 it can be convenient to use a low-level debugger such as gdb in

index.rst

@@ -2,6 +2,8 @@
 Python Developer's Guide
 ========================
 
+.. highlight:: bash
+
 This guide is a comprehensive resource for :ref:`contributing <contributing>`
 to Python_ -- for both new and experienced contributors.  It is
 :ref:`maintained <helping-with-the-developers-guide>` by the same community
@@ -27,7 +29,9 @@ instructions please see the :ref:`setup guide <setup>`.
 
       ./configure --with-pydebug && make -j
 
-   and on Windows use::
+   and on Windows use:
+
+   .. code-block:: dosbatch
 
       PCbuild\build.bat -e -d
 

pullrequest.rst

@@ -3,6 +3,7 @@
 Lifecycle of a Pull Request
 ===========================
 
+.. highlight:: bash
 
 Introduction
 ------------
@@ -171,9 +172,11 @@ through the common patch generation checks. To run ``patchcheck``:
 
       make patchcheck
 
-   On *Windows* (after any successful build)::
+   On *Windows* (after any successful build):
 
-      python.bat Tools/scripts/patchcheck.py
+   .. code-block:: dosbatch
+
+      python.bat Tools\scripts\patchcheck.py
 
 The automated patch checklist runs through: