Add some documentation for working with other plugins

- move pytest-dependency and pytest-xdists paragraphs into that chapter
- add paragraph about pytest-randomly and similar plugins

Author: mrbean-bremen

docs/source/conf.py

@@ -54,7 +54,6 @@
 
 # General information about the project.
 project = u"pytest-order"
-copyright = u"2014, Frank Tobia"
 
 # The version info for the project you"re documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -176,7 +175,7 @@
 html_show_sphinx = False
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-# html_show_copyright = True
+html_show_copyright = False
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the

docs/source/index.rst

@@ -457,17 +457,6 @@ ones. This means that relative ordering always takes preference:
 In this case, ``test_second`` will be executed before ``test_first``,
 regardless of the ordinal markers.
 
-Relationship with pytest-dependency
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The `pytest-dependency <https://pypi.org/project/pytest-dependency/>`__
-plugin also manages dependencies between tests (skips tests that depend
-on skipped or failed tests), but currently doesn't do any ordering. If you
-want to execute the tests in a specific order to each other, you can use
-``pytest-order``. If you want to skip or xfail tests dependent on other
-tests you can use ``pytest-dependency``. If you want to have both behaviors
-combined, you can use both plugins together with the
-option :ref:`order-dependencies`, described below.
-
 Configuration
 =============
 There are a few command line options that change the behavior of the
@@ -832,6 +821,8 @@ This will also work with dependency markers if using the
 .. note::
   This option will not work together well with the sparse ordering option.
 
+.. _indulgent-ordering:
+
 ``--indulgent-ordering``
 ------------------------
 You may sometimes find that you want to suggest an ordering of tests, while
@@ -1000,20 +991,86 @@ adds ordering to the existing functionality if needed.
   This feature is considered experimental. It may not handle all cases of
   defined dependencies. Please write an issue if you find any problems.
 
-Miscellaneous
-=============
+Using pytest-order with other pytest plugins
+============================================
+
+Relationship with pytest-dependency
+-----------------------------------
+The `pytest-dependency <https://pypi.org/project/pytest-dependency/>`__
+plugin also manages dependencies between tests (skips tests that depend
+on skipped or failed tests), but currently doesn't do any ordering. If you
+want to execute the tests in a specific order to each other, you can use
+``pytest-order``. If you want to skip or xfail tests dependent on other
+tests you can use ``pytest-dependency``. If you want to have both behaviors
+combined, you can use both plugins together with the
+option :ref:`order-dependencies`, described above.
+
+Using together with pytest-randomly
+-----------------------------------
+There is a number of other pytest plugins that change the order in which tests
+are executed, the most widely known probably being
+`pytest-randomly <https://pypi.org/project/pytest-randomly/>`__, which
+executes tests in a random order to avoid unknown test dependencies.
+``pytest-order`` should still work with these as long as it is executed
+*after* the other plugins (which it should by default, except if you use
+the option :ref:`indulgent-ordering`).
+The marked tests still shall be ordered correctly, but the order of the
+unordered tests will change, depending on the order the tests have been
+after these other plugins have reordered them.
+For example, if you have installed ``pytest-randomly``, and run the
+following tests:
+
+.. code:: python
+
+ import pytest
+
+ @pytest.mark.order(1)
+ def test_second():
+     assert True
+
+ def test_third():
+     assert True
+
+ def test_fourth():
+     assert True
+
+ @pytest.mark.order(0)
+ def test_first():
+     assert True
+
+the output could either be:
+
+::
+
+    test_randomly.py::test_first PASSED
+    test_randomly.py::test_second PASSED
+    test_randomly.py::test_third PASSED
+    test_randomly.py::test_fourth PASSED
+
+or:
+
+::
+
+    test_randomly.py::test_first PASSED
+    test_randomly.py::test_second PASSED
+    test_randomly.py::test_fourth PASSED
+    test_randomly.py::test_third PASSED
+
+The same is true for relative ordering. The tests will be correctly ordered
+before and after the tests as configured, but all other tests will be in an
+arbitrary order.
+
 
 Usage with pytest-xdist
 -----------------------
-The ``pytest-xdist`` plugin schedules tests unordered, and the order
-configured by ``pytest-order`` will normally not be preserved. But
-if we use the ``--dist=loadfile`` option, provided by ``xdist``, all tests
-from one file will be run in the same thread. So, to make the two plugins work
-together, we have to put each group of dependent tests in one file, and call
-pytest with ``--dist=loadfile`` (this is taken from
+The `pytest-xdist <https://pypi.org/project/pytest-xdist/>`__ plugin
+schedules tests unordered, and the order configured by ``pytest-order``
+will normally not be preserved. But if we use the ``--dist=loadfile``
+option, provided by ``xdist``, all tests from one file will be run in the
+same thread. So, to make the two plugins work together, we have to put
+each group of dependent tests in one file, and call pytest with
+``--dist=loadfile`` (this is taken from
 `this issue <https://github.com/ftobia/pytest-ordering/issues/36>`__).
 
 .. toctree::
    :maxdepth: 2
-
-.. _markers: https://pytest.org/latest/mark.html