Documentation updates

- more changes to pytest-ordering2
- some documenation consolidation, moved aspirational part
  (already implemented)

Author: mrbean-bremen

docs/source/conf.py

@@ -12,7 +12,6 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
 
 __here__ = os.path.abspath(os.path.dirname(__file__))
@@ -35,6 +34,7 @@
     'sphinx.ext.doctest',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',  # puts .nojekyll file into source
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -50,7 +50,7 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'pytest-ordering'
+project = u'pytest-ordering2'
 copyright = u'2014, Frank Tobia'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -171,7 +171,7 @@
 #html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
+html_show_sphinx = False
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
 #html_show_copyright = True
@@ -205,7 +205,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  ('index', 'pytest-ordering.tex', u'pytest-ordering Documentation',
+  ('index', 'pytest-ordering.tex', u'pytest-ordering2 Documentation',
    u'Frank Tobia', 'manual'),
 ]
 
@@ -235,7 +235,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'pytest-ordering', u'pytest-ordering Documentation',
+    ('index', 'pytest-ordering2', u'pytest-ordering2 Documentation',
      [u'Frank Tobia'], 1)
 ]
 
@@ -249,8 +249,8 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'pytest-ordering', u'pytest-ordering Documentation',
-   u'Frank Tobia', 'pytest-ordering', 'One line description of project.',
+  ('index', 'pytest-ordering2', u'pytest-ordering2 Documentation',
+   u'Frank Tobia', 'pytest-ordering2', 'One line description of project.',
    'Miscellaneous'),
 ]
 

docs/source/index.rst

@@ -3,23 +3,18 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-pytest-ordering: run your tests in  order
-=========================================
+pytest-ordering2: run your tests in  order
+==========================================
 
-pytest-ordering is a pytest plugin to run your tests in any order that
+pytest-ordering2 is a pytest plugin to run your tests in any order that
 you specify. It provides custom markers_ that say when your tests should
 run in relation to each other. They can be absolute (i.e. first, or
 second-to-last) or relative (i.e. run this test before this other test).
 
-.. note :: pytest-ordering is currently alpha-quality software. Notably,
- some of this documentation may be aspirational in nature. If something
- you read here isn't currently implemented, rest assured that I am working
- on it (or feel free to ping me: https://github.com/ftobia)
-
-Supported python and pytest versions
+Supported Python and pytest versions
 ------------------------------------
 
-pytest-ordering supports python 2.7, 3.4, 3.5, 3.6, 3.7, and pypy, and is
+pytest-ordering2 supports python 2.7, 3.5 - 3.8, and pypy, and is
 compatible with pytest 3.6.0 or newer.
 
 
@@ -57,11 +52,11 @@ With pytest-ordering, you can change the default ordering as follows:
 
  import pytest
 
- @pytest.mark.order2
+ @pytest.mark.run(order=2)
  def test_foo():
      assert True
 
- @pytest.mark.order1
+ @pytest.mark..run(order=1)
  def test_bar():
      assert True
 
@@ -79,29 +74,31 @@ With pytest-ordering, you can change the default ordering as follows:
     =========================== 2 passed in 0.01 seconds ===========================
 
 This is a trivial example, but ordering is respected across test files.
+There are several possibilities to define the order.
 
-Other markers
--------------
-
-You can also use markers such as "first", "second", "last", and "second_to_last":
+By number
+---------
+As already shown above, the order can be defined using ordinal numbers.
+Negative numbers are also allowed - they are used the same way as indexes
+used in Python lists, e.g. to count from the end:
 
 .. code:: python
 
  import pytest
 
- @pytest.mark.second_to_last
+ @pytest.mark.run(order=-2)
  def test_three():
      assert True
 
- @pytest.mark.last
+ @pytest.mark.run(order=-1)
  def test_four():
      assert True
 
- @pytest.mark.second
+ @pytest.mark.run(order=2)
  def test_two():
      assert True
 
- @pytest.mark.first
+ @pytest.mark.run(order=1)
  def test_one():
      assert True
 
@@ -120,87 +117,31 @@ You can also use markers such as "first", "second", "last", and "second_to_last"
 
     =========================== 4 passed in 0.02 seconds ===========================
 
-``--indulgent-ordering`` and overriding ordering
--------------
-
-You may sometimes find that you want to suggest an ordering of tests, while
-allowing it to be overridden for good reson. For example, if you run your test
-suite in parallel and have a number of tests which are particularly slow, it
-might be desirable to start those tests running first, in order to optimize
-your completion time. You can use the pytest-ordering plugin to inform pytest
-of this. Now suppose you also want to prioritize tests which failed during the
-previous run, by using the ``--failed-first`` option. By default,
-pytest-ordering will override the ``--failed-first`` order, but by adding the
-``--indulgent-ordering`` option, you can ask pytest to run the sort from
-pytest-ordering *before* the sort from ``--failed-first``, allowing the failed
-tests to be sorted to the front.
-
-
-Aspirational
-============
-
-This section is for functionality I'd like to implement.
-Documentation-driven design :)
 
 Ordinals
 --------
 
-.. code:: python
-
- import pytest
-
- @pytest.mark.run('second-to-last')
- def test_three():
-     assert True
-
- @pytest.mark.run('last')
- def test_four():
-     assert True
-
- @pytest.mark.run('second')
- def test_two():
-     assert True
-
- @pytest.mark.run('first')
- def test_one():
-     assert True
-
-::
-
-    $ py.test test_foo.py -vv
-    ============================= test session starts ==============================
-    platform darwin -- Python 2.7.5 -- py-1.4.20 -- pytest-2.5.2 -- env/bin/python
-    plugins: ordering
-    collected 4 items
-
-    test_foo.py:17: test_one PASSED
-    test_foo.py:12: test_two PASSED
-    test_foo.py:3: test_three PASSED
-    test_foo.py:7: test_four PASSED
-
-    =========================== 4 passed in 0.02 seconds ===========================
-
-
-By number
----------
+You can also use markers such as "first", "second", "last", and
+"second_to_last". These are convenience notations, and have the same effect
+as the numbers 1, 2, -1 and -2 that have been shown above:
 
 .. code:: python
 
  import pytest
 
- @pytest.mark.run(order=-2)
+ @pytest.mark.second_to_last
  def test_three():
      assert True
 
- @pytest.mark.run(order=-1)
+ @pytest.mark.last
  def test_four():
      assert True
 
- @pytest.mark.run(order=2)
+ @pytest.mark.second
  def test_two():
      assert True
 
- @pytest.mark.run(order=1)
+ @pytest.mark.first
  def test_one():
      assert True
 
@@ -219,10 +160,11 @@ By number
 
     =========================== 4 passed in 0.02 seconds ===========================
 
-
 Relative to other tests
 -----------------------
 
+The test order can be defined relative to other tests, which are referenced
+by their name:
 
 .. code:: python
 
@@ -253,6 +195,22 @@ Relative to other tests
 
     =========================== 4 passed in 0.02 seconds ===========================
 
+``--indulgent-ordering`` and overriding ordering
+------------------------------------------------
+
+You may sometimes find that you want to suggest an ordering of tests, while
+allowing it to be overridden for good reason. For example, if you run your test
+suite in parallel and have a number of tests which are particularly slow, it
+might be desirable to start those tests running first, in order to optimize
+your completion time. You can use the pytest-ordering2 plugin to inform pytest
+of this.
+Now suppose you also want to prioritize tests which failed during the
+previous run, by using the ``--failed-first`` option. By default,
+pytest-ordering will override the ``--failed-first`` order, but by adding the
+``--indulgent-ordering`` option, you can ask pytest to run the sort from
+pytest-ordering2 *before* the sort from ``--failed-first``, allowing the failed
+tests to be sorted to the front.
+
 
 
 .. toctree::