Merge pull request #4783 from gyermolenko/fix_syntax_highlighting_for_two_rst_docs

Fix sphinx code-block types (syntax highlighting) in two docs
2019-02-20 06:31:10 +11:00 · 2019-02-20 06:31:10 +11:00 · c8a87e48ab
parent bf6dcd64dc 6e1ee0802f
commit c8a87e48ab
17 changed files with 212 additions and 79 deletions
--- a/doc/en/bash-completion.rst
+++ b/doc/en/bash-completion.rst
@ -8,18 +8,26 @@ When using bash as your shell, ``pytest`` can use argcomplete
 (https://argcomplete.readthedocs.io/) for auto-completion.
 For this ``argcomplete`` needs to be installed **and** enabled.

-Install argcomplete using::
+Install argcomplete using:
+
+.. code-block:: bash

    sudo pip install 'argcomplete>=0.5.7'

-For global activation of all argcomplete enabled python applications run::
+For global activation of all argcomplete enabled python applications run:
+
+.. code-block:: bash

    sudo activate-global-python-argcomplete

-For permanent (but not global) ``pytest`` activation, use::
+For permanent (but not global) ``pytest`` activation, use:
+
+.. code-block:: bash

    register-python-argcomplete pytest >> ~/.bashrc

-For one-time activation of argcomplete for ``pytest`` only, use::
+For one-time activation of argcomplete for ``pytest`` only, use:
+
+.. code-block:: bash

    eval "$(register-python-argcomplete pytest)"
--- a/doc/en/cache.rst
+++ b/doc/en/cache.rst
@ -168,7 +168,9 @@ Behavior when no tests failed in the last run

 When no tests failed in the last run, or when no cached ``lastfailed`` data was
 found, ``pytest`` can be configured either to run all of the tests or no tests,
-using the ``--last-failed-no-failures`` option, which takes one of the following values::
+using the ``--last-failed-no-failures`` option, which takes one of the following values:
+
+.. code-block:: bash

    pytest --last-failed --last-failed-no-failures all    # run all tests (default behavior)
    pytest --last-failed --last-failed-no-failures none   # run no tests and exit
@ -283,7 +285,9 @@ Clearing Cache content
 -------------------------------

 You can instruct pytest to clear all cache files and values
-by adding the ``--cache-clear`` option like this::
+by adding the ``--cache-clear`` option like this:
+
+.. code-block:: bash

    pytest --cache-clear

--- a/doc/en/capture.rst
+++ b/doc/en/capture.rst
@ -35,7 +35,9 @@ There are two ways in which ``pytest`` can perform capturing:

 .. _`disable capturing`:

-You can influence output capturing mechanisms from the command line::
+You can influence output capturing mechanisms from the command line:
+
+.. code-block:: bash

    pytest -s            # disable all capturing
    pytest --capture=sys # replace sys.stdout/stderr with in-mem files
--- a/doc/en/customize.rst
+++ b/doc/en/customize.rst
@ -5,7 +5,9 @@ Command line options and configuration file settings
 -----------------------------------------------------------------

 You can get help on command line options and values in INI-style
-configurations files by using the general help option::
+configurations files by using the general help option:
+
+.. code-block:: bash

    pytest -h   # prints options _and_ config file settings

@ -92,12 +94,16 @@ The rootdir is used a reference directory for constructing test
 addresses ("nodeids") and can be used also by plugins for storing
 per-testrun information.

-Example::
+Example:
+
+.. code-block:: bash

    pytest path/to/testdir path/other/

 will determine the common ancestor as ``path`` and then
-check for ini-files as follows::
+check for ini-files as follows:
+
+.. code-block:: text

    # first look for pytest.ini files
    path/pytest.ini
@ -133,19 +139,27 @@ progress output, you can write it into a configuration file:
    addopts = -ra -q

 Alternatively, you can set a ``PYTEST_ADDOPTS`` environment variable to add command
-line options while the environment is in use::
+line options while the environment is in use:
+
+.. code-block:: bash

    export PYTEST_ADDOPTS="-v"

-Here's how the command-line is built in the presence of ``addopts`` or the environment variable::
+Here's how the command-line is built in the presence of ``addopts`` or the environment variable:
+
+.. code-block:: text

    <pytest.ini:addopts> $PYTEST_ADDOPTS <extra command-line arguments>

-So if the user executes in the command-line::
+So if the user executes in the command-line:
+
+.. code-block:: bash

    pytest -m slow

-The actual command line executed is::
+The actual command line executed is:
+
+.. code-block:: bash

    pytest -ra -q -v -m slow

--- a/doc/en/doctest.rst
+++ b/doc/en/doctest.rst
@ -4,7 +4,9 @@ Doctest integration for modules and test files

 By default all files matching the ``test*.txt`` pattern will
 be run through the python standard ``doctest`` module.  You
-can change the pattern by issuing::
+can change the pattern by issuing:
+
+.. code-block:: bash

    pytest --doctest-glob='*.rst'

@ -26,7 +28,9 @@ can be given multiple times in the command-line.

 You can also trigger running of doctests
 from docstrings in all python modules (including regular
-python test modules)::
+python test modules):
+
+.. code-block:: bash

    pytest --doctest-modules

@ -39,7 +43,9 @@ putting them into a pytest.ini file like this:
    [pytest]
    addopts = --doctest-modules

-If you then have a text file like this::
+If you then have a text file like this:
+
+.. code-block:: text

    # content of example.rst

@ -73,7 +79,9 @@ then you can just invoke ``pytest`` without command line options:

    ========================= 1 passed in 0.12 seconds =========================

-It is possible to use fixtures using the ``getfixture`` helper::
+It is possible to use fixtures using the ``getfixture`` helper:
+
+.. code-block:: text

    # content of example.rst
    >>> tmp = getfixture('tmpdir')
@ -112,14 +120,18 @@ the ``doctest_optionflags`` ini option:


 Alternatively, it can be enabled by an inline comment in the doc test
-itself::
+itself:
+
+.. code-block:: rst

    # content of example.rst
    >>> get_unicode_greeting()  # doctest: +ALLOW_UNICODE
    'Hello'

 By default, pytest would report only the first failure for a given doctest.  If
-you want to continue the test even when you have failures, do::
+you want to continue the test even when you have failures, do:
+
+.. code-block:: bash

    pytest --doctest-modules --doctest-continue-on-failure

@ -167,7 +179,9 @@ Output format
 You can change the diff output format on failure for your doctests
 by using one of standard doctest modules format in options
 (see :data:`python:doctest.REPORT_UDIFF`, :data:`python:doctest.REPORT_CDIFF`,
-:data:`python:doctest.REPORT_NDIFF`, :data:`python:doctest.REPORT_ONLY_FIRST_FAILURE`)::
+:data:`python:doctest.REPORT_NDIFF`, :data:`python:doctest.REPORT_ONLY_FIRST_FAILURE`):
+
+.. code-block:: bash

    pytest --doctest-modules --doctest-report none
    pytest --doctest-modules --doctest-report udiff
--- a/doc/en/example/markers.rst
+++ b/doc/en/example/markers.rst
@ -204,14 +204,18 @@ Registering markers

 .. ini-syntax for custom markers:

-Registering markers for your test suite is simple::
+Registering markers for your test suite is simple:
+
+.. code-block:: ini

    # content of pytest.ini
    [pytest]
    markers =
        webtest: mark a test as a webtest.

-You can ask which markers exist for your test suite - the list includes our just defined ``webtest`` markers::
+You can ask which markers exist for your test suite - the list includes our just defined ``webtest`` markers:
+
+.. code-block:: pytest

    $ pytest --markers
    @pytest.mark.webtest: mark a test as a webtest.
@ -388,7 +392,9 @@ and here is one that specifies exactly the environment needed:

    ========================= 1 passed in 0.12 seconds =========================

-The ``--markers`` option always gives you a list of available markers::
+The ``--markers`` option always gives you a list of available markers:
+
+.. code-block:: pytest

    $ pytest --markers
    @pytest.mark.env(name): mark test to run only on named environment
--- a/doc/en/example/pythoncollection.rst
+++ b/doc/en/example/pythoncollection.rst
@ -6,7 +6,9 @@ Ignore paths during test collection

 You can easily ignore certain test directories and modules during collection
 by passing the ``--ignore=path`` option on the cli. ``pytest`` allows multiple
-``--ignore`` options. Example::
+``--ignore`` options. Example:
+
+.. code-block:: text

    tests/
    |-- example
@ -57,7 +59,9 @@ Keeping duplicate paths specified from command line
 ----------------------------------------------------

 Default behavior of ``pytest`` is to ignore duplicate paths specified from the command line.
-Example::
+Example:
+
+.. code-block:: pytest

    pytest path_a path_a

@ -68,7 +72,9 @@ Example::
 Just collect tests once.

 To collect duplicate tests, use the ``--keep-duplicates`` option on the cli.
-Example::
+Example:
+
+.. code-block:: pytest

    pytest --keep-duplicates path_a path_a

@ -78,7 +84,9 @@ Example::

 As the collector just works on directories, if you specify twice a single test file, ``pytest`` will
 still collect it twice, no matter if the ``--keep-duplicates`` is not specified.
-Example::
+Example:
+
+.. code-block:: pytest

    pytest test_a.py test_a.py

@ -90,7 +98,9 @@ Example::
 Changing directory recursion
 -----------------------------------------------------

-You can set the :confval:`norecursedirs` option in an ini-file, for example your ``pytest.ini`` in the project root directory::
+You can set the :confval:`norecursedirs` option in an ini-file, for example your ``pytest.ini`` in the project root directory:
+
+.. code-block:: ini

    # content of pytest.ini
    [pytest]
@ -106,7 +116,9 @@ Changing naming conventions
 You can configure different naming conventions by setting
 the :confval:`python_files`, :confval:`python_classes` and
 :confval:`python_functions` configuration options.
-Here is an example::
+Here is an example:
+
+.. code-block:: ini

    # content of pytest.ini
    # Example 1: have pytest look for "check" instead of "test"
@ -145,7 +157,9 @@ The test collection would look like this:

    ======================= no tests ran in 0.12 seconds =======================

-You can check for multiple glob patterns by adding a space between the patterns::
+You can check for multiple glob patterns by adding a space between the patterns:
+
+.. code-block:: ini

    # Example 2: have pytest look for files with "test" and "example"
    # content of pytest.ini, tox.ini, or setup.cfg file (replace "pytest"
@ -165,13 +179,17 @@ Interpreting cmdline arguments as Python packages
 You can use the ``--pyargs`` option to make ``pytest`` try
 interpreting arguments as python package names, deriving
 their file system path and then running the test. For
-example if you have unittest2 installed you can type::
+example if you have unittest2 installed you can type:
+
+.. code-block:: bash

    pytest --pyargs unittest2.test.test_skipping -q

 which would run the respective test module.  Like with
 other options, through an ini-file and the :confval:`addopts` option you
-can make this change more permanently::
+can make this change more permanently:
+
+.. code-block:: ini

    # content of pytest.ini
    [pytest]
@ -209,7 +227,9 @@ Customizing test collection

 .. regendoc:wipe

-You can easily instruct ``pytest`` to discover tests from every Python file::
+You can easily instruct ``pytest`` to discover tests from every Python file:
+
+.. code-block:: ini

    # content of pytest.ini
    [pytest]
--- a/doc/en/example/simple.rst
+++ b/doc/en/example/simple.rst
@ -731,7 +731,9 @@ and run them:
    test_module.py:6: AssertionError
    ========================= 2 failed in 0.12 seconds =========================

-you will have a "failures" file which contains the failing test ids::
+you will have a "failures" file which contains the failing test ids:
+
+.. code-block:: bash

    $ cat failures
    test_module.py::test_fail1 (PYTEST_TMPDIR/test_fail10)
@ -935,6 +937,8 @@ like ``pytest-timeout`` they must be imported explicitly and passed on to pytest


 This allows you to execute tests using the frozen
-application with standard ``pytest`` command-line options::
+application with standard ``pytest`` command-line options:
+
+.. code-block:: bash

    ./app_main --pytest --verbose --tb=long --junitxml=results.xml test-suite/
--- a/doc/en/fixture.rst
+++ b/doc/en/fixture.rst
@ -114,7 +114,9 @@ with a list of available function arguments.

 .. note::

-    You can always issue ::
+    You can always issue:
+
+    .. code-block:: bash

        pytest --fixtures test_simplefactory.py

@ -362,7 +364,9 @@ The ``print`` and ``smtp.close()`` statements will execute when the last test in
 the module has finished execution, regardless of the exception status of the
 tests.

-Let's execute it::
+Let's execute it:
+
+.. code-block:: pytest

    $ pytest -s -q --tb=no
    FFteardown smtp
@ -471,7 +475,9 @@ read an optional server URL from the test module which uses our fixture::

 We use the ``request.module`` attribute to optionally obtain an
 ``smtpserver`` attribute from the test module.  If we just execute
-again, nothing much has changed::
+again, nothing much has changed:
+
+.. code-block:: pytest

    $ pytest -s -q --tb=no
    FFfinalizing <smtplib.SMTP object at 0xdeadbeef> (smtp.gmail.com)
--- a/doc/en/getting-started.rst
+++ b/doc/en/getting-started.rst
@ -17,11 +17,15 @@ Installation and Getting Started
 Install ``pytest``
 ----------------------------------------

-1. Run the following command in your command line::
+1. Run the following command in your command line:
+
+.. code-block:: bash

    pip install -U pytest

-2. Check that you installed the correct version::
+2. Check that you installed the correct version:
+
+.. code-block:: bash

    $ pytest --version
    This is pytest version 4.x.y, imported from $PYTHON_PREFIX/lib/python3.6/site-packages/pytest.py
@ -168,7 +172,9 @@ List the name ``tmpdir`` in the test function signature and ``pytest`` will look

 More info on tmpdir handling is available at :ref:`Temporary directories and files <tmpdir handling>`.

-Find out what kind of builtin :ref:`pytest fixtures <fixtures>` exist with the command::
+Find out what kind of builtin :ref:`pytest fixtures <fixtures>` exist with the command:
+
+.. code-block:: bash

    pytest --fixtures   # shows builtin and custom fixtures

--- a/doc/en/license.rst
+++ b/doc/en/license.rst
@ -5,7 +5,7 @@ License

 Distributed under the terms of the `MIT`_ license, pytest is free and open source software.

-::
+.. code-block:: text

    The MIT License (MIT)

--- a/doc/en/logging.rst
+++ b/doc/en/logging.rst
@ -9,11 +9,15 @@ Logging
 pytest captures log messages of level ``WARNING`` or above automatically and displays them in their own section
 for each failed test in the same manner as captured stdout and stderr.

-Running without options::
+Running without options:
+
+.. code-block:: bash

    pytest

-Shows failed tests like so::
+Shows failed tests like so:
+
+.. code-block:: pytest

    ----------------------- Captured stdlog call ----------------------
    test_reporting.py    26 WARNING  text going to logger
@ -27,12 +31,16 @@ By default each captured log message shows the module, line number, log level
 and message.

 If desired the log and date format can be specified to
-anything that the logging module supports by passing specific formatting options::
+anything that the logging module supports by passing specific formatting options:
+
+.. code-block:: bash

    pytest --log-format="%(asctime)s %(levelname)s %(message)s" \
            --log-date-format="%Y-%m-%d %H:%M:%S"

-Shows failed tests like so::
+Shows failed tests like so:
+
+.. code-block:: pytest

    ----------------------- Captured stdlog call ----------------------
    2010-04-10 14:48:44 WARNING text going to logger
@ -51,7 +59,9 @@ These options can also be customized through ``pytest.ini`` file:
    log_date_format = %Y-%m-%d %H:%M:%S

 Further it is possible to disable reporting of captured content (stdout,
-stderr and logs) on failed tests completely with::
+stderr and logs) on failed tests completely with:
+
+.. code-block:: bash

    pytest --show-capture=no

@ -133,7 +143,6 @@ the records for the ``setup`` and ``call`` stages during teardown like so:

 .. code-block:: python

-
    @pytest.fixture
    def window(caplog):
        window = create_window()
--- a/doc/en/nose.rst
+++ b/doc/en/nose.rst
@ -12,7 +12,9 @@ Running tests written for nose
 Usage
 -------------

-After :ref:`installation` type::
+After :ref:`installation` type:
+
+.. code-block:: bash

    python setup.py develop  # make sure tests can import our package
    pytest  # instead of 'nosetests'
--- a/doc/en/parametrize.rst
+++ b/doc/en/parametrize.rst
@ -172,7 +172,9 @@ command line option and the parametrization of our test function::
            metafunc.parametrize("stringinput",
                                 metafunc.config.getoption('stringinput'))

-If we now pass two stringinput values, our test will run twice::
+If we now pass two stringinput values, our test will run twice:
+
+.. code-block:: pytest

    $ pytest -q --stringinput="hello" --stringinput="world" test_strings.py
    ..                                                                   [100%]
--- a/doc/en/skipping.rst
+++ b/doc/en/skipping.rst
@ -22,7 +22,9 @@ it's an **xpass** and will be reported in the test summary.
 ``pytest`` counts and lists *skip* and *xfail* tests separately. Detailed
 information about skipped/xfailed tests is not shown by default to avoid
 cluttering the output.  You can use the ``-r`` option to see details
-corresponding to the "short" letters shown in the test progress::
+corresponding to the "short" letters shown in the test progress:
+
+.. code-block:: bash

    pytest -rxXs  # show extra info on xfailed, xpassed, and skipped tests

@ -82,7 +84,7 @@ It is also possible to skip the whole module using

 If you wish to skip something conditionally then you can use ``skipif`` instead.
 Here is an example of marking a test function to be skipped
-when run on an interpreter earlier than Python3.6 ::
+when run on an interpreter earlier than Python3.6::

    import sys
    @pytest.mark.skipif(sys.version_info < (3,6),
@ -309,7 +311,9 @@ investigated later.
 Ignoring xfail
 ~~~~~~~~~~~~~~

-By specifying on the commandline::
+By specifying on the commandline:
+
+.. code-block:: bash

    pytest --runxfail

--- a/doc/en/tmpdir.rst
+++ b/doc/en/tmpdir.rst
@ -174,7 +174,9 @@ the system temporary directory.  The base name will be ``pytest-NUM`` where
 ``NUM`` will be incremented with each test run.  Moreover, entries older
 than 3 temporary directories will be removed.

-You can override the default temporary directory setting like this::
+You can override the default temporary directory setting like this:
+
+.. code-block:: bash

    pytest --basetemp=mydir

--- a/doc/en/usage.rst
+++ b/doc/en/usage.rst
@ -12,7 +12,9 @@ Calling pytest through ``python -m pytest``

 .. versionadded:: 2.0

-You can invoke testing through the Python interpreter from the command line::
+You can invoke testing through the Python interpreter from the command line:
+
+.. code-block:: text

    python -m pytest [...]

@ -34,7 +36,7 @@ Running ``pytest`` can result in six different exit codes:
 Getting help on version, option names, environment variables
 --------------------------------------------------------------

-::
+.. code-block:: bash

    pytest --version   # shows where pytest was imported from
    pytest --fixtures  # show available builtin function arguments
@ -46,7 +48,9 @@ Getting help on version, option names, environment variables
 Stopping after the first (or N) failures
 ---------------------------------------------------

-To stop the testing process after the first (N) failures::
+To stop the testing process after the first (N) failures:
+
+.. code-block:: bash

    pytest -x            # stop after first failure
    pytest --maxfail=2    # stop after two failures
@ -60,19 +64,19 @@ Pytest supports several ways to run and select tests from the command-line.

 **Run tests in a module**

-::
+.. code-block:: bash

    pytest test_mod.py

 **Run tests in a directory**

-::
+.. code-block:: bash

    pytest testing/

 **Run tests by keyword expressions**

-::
+.. code-block:: bash

    pytest -k "MyClass and not method"

@ -87,18 +91,22 @@ The example above will run ``TestMyClass.test_something``  but not ``TestMyClass
 Each collected test is assigned a unique ``nodeid`` which consist of the module filename followed
 by specifiers like class names, function names and parameters from parametrization, separated by ``::`` characters.

-To run a specific test within a module::
+To run a specific test within a module:
+
+.. code-block:: bash

    pytest test_mod.py::test_func


-Another example specifying a test method in the command line::
+Another example specifying a test method in the command line:
+
+.. code-block:: bash

    pytest test_mod.py::TestClass::test_method

 **Run tests by marker expressions**

-::
+.. code-block:: bash

    pytest -m slow

@ -108,7 +116,7 @@ For more information see :ref:`marks <mark>`.

 **Run tests from packages**

-::
+.. code-block:: bash

    pytest --pyargs pkg.testing

@ -118,7 +126,9 @@ This will import ``pkg.testing`` and use its filesystem location to find and run
 Modifying Python traceback printing
 ----------------------------------------------

-Examples for modifying traceback printing::
+Examples for modifying traceback printing:
+
+.. code-block:: bash

    pytest --showlocals # show local variables in tracebacks
    pytest -l           # show local variables (shortcut)
@ -320,13 +330,17 @@ Dropping to PDB_ (Python Debugger) on failures
 .. _PDB: http://docs.python.org/library/pdb.html

 Python comes with a builtin Python debugger called PDB_.  ``pytest``
-allows one to drop into the PDB_ prompt via a command line option::
+allows one to drop into the PDB_ prompt via a command line option:
+
+.. code-block:: bash

    pytest --pdb

 This will invoke the Python debugger on every failure (or KeyboardInterrupt).
 Often you might only want to do this for the first failing test to understand
-a certain failure situation::
+a certain failure situation:
+
+.. code-block:: bash

    pytest -x --pdb   # drop to PDB on first failure, then end test session
    pytest --pdb --maxfail=3  # drop to PDB for first three failures
@ -349,7 +363,9 @@ Dropping to PDB_ (Python Debugger) at the start of a test
 ----------------------------------------------------------


-``pytest`` allows one to drop into the PDB_ prompt immediately at the start of each test via a command line option::
+``pytest`` allows one to drop into the PDB_ prompt immediately at the start of each test via a command line option:
+
+.. code-block:: bash

    pytest --trace

@ -394,7 +410,9 @@ Profiling test execution duration

 .. versionadded: 2.2

-To get a list of the slowest 10 test durations::
+To get a list of the slowest 10 test durations:
+
+.. code-block:: bash

    pytest --durations=10

@ -404,7 +422,9 @@ Creating JUnitXML format files
 ----------------------------------------------------

 To create result files which can be read by Jenkins_ or other Continuous
-integration servers, use this invocation::
+integration servers, use this invocation:
+
+.. code-block:: bash

    pytest --junitxml=path

@ -627,7 +647,9 @@ Creating resultlog format files
    See `the deprecation docs <https://docs.pytest.org/en/latest/deprecations.html#result-log-result-log>`__
    for more information.

-To create plain-text machine-readable result files you can issue::
+To create plain-text machine-readable result files you can issue:
+
+.. code-block:: bash

    pytest --resultlog=path

@ -640,7 +662,9 @@ by the `PyPy-test`_ web page to show test results over several revisions.
 Sending test report to online pastebin service
 -----------------------------------------------------

-**Creating a URL for each test failure**::
+**Creating a URL for each test failure**:
+
+.. code-block:: bash

    pytest --pastebin=failed

@ -648,7 +672,9 @@ This will submit test run information to a remote Paste service and
 provide a URL for each failure.  You may select tests as usual or add
 for example ``-x`` if you only want to send one particular failure.

-**Creating a URL for a whole test session log**::
+**Creating a URL for a whole test session log**:
+
+.. code-block:: bash

    pytest --pastebin=all

@ -661,7 +687,9 @@ To disable loading specific plugins at invocation time, use the ``-p`` option
 together with the prefix ``no:``.

 Example: to disable loading the plugin ``doctest``, which is responsible for
-executing doctest tests from text files, invoke pytest like this::
+executing doctest tests from text files, invoke pytest like this:
+
+.. code-block:: bash

    pytest -p no:doctest

@ -693,7 +721,9 @@ You can specify additional plugins to ``pytest.main``::
    pytest.main(["-qq"], plugins=[MyPlugin()])

 Running it will show that ``MyPlugin`` was added and its
-hook was invoked::
+hook was invoked:
+
+.. code-block:: pytest

    $ python myinvoke.py
    .FEsxX.                                                              [100%]*** test run reporting finishing