Documentation update

- add automatic documentation build
- minor documentation cleanup, change theme to nature

Author: mrbean-bremen

.travis.yml

@@ -7,6 +7,9 @@ python:
   - "3.7"
   - "3.8"
   - "pypy"
+env:
+  global:
+    secure: T6vjQsfhlpCwD0dsVZxDbUD5rvqiOz27ex3nwGvVFWnu0ospPbqzw1MqZcjyFvwcLWF+TrJbVf7UxxTM4JHESZTwcSQ1zXhzZ/pRhCKRa7q7fbVkMptEuarUVmnZZAs9GqZecetCA+ka5dSlHEJdIZwyHRmGV8hOx2w/OHRLEJTpSxT7NTkoKTATPxEzseAup1cJ47PGpnLQYXc0H2DgedgUqboU35Rkbya38gptKqFJJ8K3VuCr+j91Pq/rTntMIND3OsBkzPF1PE08tC15G9bBwRi+nER0BZSfxKkmoTLh7yDJhyyzuTDedaZInCziRYCbhQfsCn8QRCyiVeRiCVt1+/2yNt5lJYZwxpQGyYMOA//zlEDu7Z1uYSnkvy4BkI5g22IrjHLcij1lAaJ3lkafINbcUqlwv4sp/xgT8VXCfiDUadvzm+O9rBo6GlVrgWvdV0ExkSWYDu77ruGHZT3XCZ5ZpTf8OtwX71yHs1o5A5lzfPf1DA+fKPiWsu8jOYlStPn5v81ppqYzIz3JiaWgypCDWB7TLWT6iFjfK5hRWNJQn7aVKx5m86Dtu2cxDdBUDhK8fhbIWAQsdyLMcsXEGK1nekxEK8oM28g0hvifQqS1Up+MXmG6xQg8inbvWuZhwE6cnjDyb5CnaI+KAVxtrhVNlYkv8405fe6XumE=
 install:
   - pip install tox
   - pip install python-coveralls
@@ -15,4 +18,6 @@ script:
   - tox -e $(tox -l | grep $TOX_PYTHON_VERSION | paste -sd "," -)
 after_success:
   - coveralls
+  - pip install sphinx
+  - ./build-docs.sh
 sudo: false

CHANGELOG.md

@@ -3,7 +3,10 @@
 ## Unreleased
 
 ### Fixes
-- fixes the handling of unknown marker attributes (test had been skipped)  
+- fixed the handling of unknown marker attributes (test had been skipped)
+
+### Infrastructure
+- added automatic documentation build on change 
 
 ## [Version 0.7.1](https://pypi.org/project/pytest-order/0.7.1/)
 Update after renaming the repository and the package.

build-docs.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Create html documentation from docs sources using sphinx
+# and check it into gh-pages branch using the same commit message.
+# Skipped if not the master branch, triggered by a pull request,
+# nothing has been changed in docs/, # or the string SKIP-AUTODOC
+# appears in the commit message.
+
+# only process after the last matrix build
+if [ "$TRAVIS_PYTHON_VERSION" != "pypy" ]; then
+  echo "Not on last matrix build, skipping"
+  exit 0
+fi
+
+SOURCE_BRANCH="master"
+TARGET_BRANCH="gh-pages"
+REPO_URL="https://${GH_TOKEN}@github.com/mrbean-bremen/pytest-order.git"
+
+if [ "$TRAVIS_BRANCH" != "$SOURCE_BRANCH" ]; then
+  echo "Not on $SOURCE_BRANCH branch, skipping"
+  exit 0
+fi
+
+if [ "$TRAVIS_PULL_REQUEST" != "false" ]; then
+  echo "This is a pull request, skipping"
+  exit 0
+fi
+
+# enable error reporting to the console
+set -e
+
+# save last commit log - will be used for the doc commit
+LAST_COMMIT=`git log -1 --pretty=%B`
+
+# all documentaion changes happen in 'docs', as we have no source code
+# documentation - only consider changes in that path
+LAST_DOC_COMMIT=`git log -1 --pretty=%B docs`
+if [ "$LAST_COMMIT" != "$LAST_DOC_COMMIT" ]; then
+  echo "No changes in documentation, skipping"
+  exit 0
+fi
+
+if [[ $LAST_COMMIT == *"SKIP-AUTODOC"* ]]; then
+  echo "Autodoc switched off in commit message, skipping"
+  exit 0
+fi
+
+# create the docs using sphinx
+cd docs
+make html
+cd ..
+
+# clone `gh-pages' branch of the repository using encrypted GH_TOKEN for authentification
+git clone $REPO_URL -b $TARGET_BRANCH ../pytest_order_gh-pages
+
+# copy generated HTML files to dev part of `gh-pages' branch
+cp -r docs/build/html/* ../pytest_order_gh-pages/dev
+
+# commit and push generated content to `gh-pages' branch
+cd ../pytest_order_gh-pages
+git config user.name "Travis CI"
+git config user.email "[email protected]"
+git commit -a -m "$LAST_COMMIT"
+git push --quiet $REPO_URL $TARGET_BRANCH > /dev/null 2>&1

docs/source/conf.py

@@ -12,14 +12,17 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import os
-
-__here__ = os.path.abspath(os.path.dirname(__file__))
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+
+sys.path.insert(
+    0, os.path.split(os.path.split(os.path.dirname(os.path.abspath(
+        __file__)))[0])[0])
+
+from pytest_order import __version__
 
 # -- General configuration ------------------------------------------------
 
@@ -57,8 +60,7 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-exec(open(os.path.join(__here__, '..', '..', 'pytest_order',
-                       '_version.py')).read())
+
 # The short X.Y version.
 version = __version__
 # The full version, including alpha/beta/rc tags.
@@ -107,7 +109,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'nature'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -136,7 +138,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/source/index.rst

@@ -1,9 +1,10 @@
-pytest-order: run your tests in  order
-======================================
-pytest-order is a pytest plugin to run your tests in any order that
-you specify. It provides the marker ``order``, that defines 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).
+Introduction
+============
+``pytest-order`` is a pytest plugin which allows you to customize the order
+in which run your tests are run. It provides the marker ``order``, that has
+attributes that defines when your tests should run in relation to each other.
+These attributes can be absolute (i.e. first, or second-to-last) or relative
+(i.e. run this test before this other test).
 
 Relationship with pytest-ordering
 ---------------------------------
@@ -46,8 +47,8 @@ The latest master can be installed from the GitHub sources:
 
    pip install git+https://github.com/mrbean-bremen/pytest-order
 
-Quickstart
-----------
+Overview
+--------
 Ordinarily pytest will run tests in the order that they appear in a module.
 For example, for the following tests:
 
@@ -100,11 +101,13 @@ With pytest-order, 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.
+Usage
+=====
+The above is a trivial example, but ordering is respected across test files.
+There are currently three possibilities to define the order:
 
-By number
----------
+Order 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
 are used in Python lists, e.g. to count from the end:
@@ -144,13 +147,14 @@ are used in Python lists, e.g. to count from the end:
 
     =========================== 4 passed in 0.02 seconds ===========================
 
+There is no limit for the numbers that can be used in this way.
 
-Ordinals
---------
+Order using ordinals
+--------------------
 
 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:
+as the numbers 0, 1, -1 and -2 that have been shown above:
 
 .. code:: python
 
@@ -187,9 +191,28 @@ as the numbers 1, 2, -1 and -2 that have been shown above:
 
     =========================== 4 passed in 0.02 seconds ===========================
 
-Relative to other tests
------------------------
-
+Convenience names are only defined for the first and the last 8 numbers, 
+here is the complete list with the corresponding numbers:
+
+- 'first': 0
+- 'second': 1
+- 'third': 2
+- 'fourth': 3
+- 'fifth': 4
+- 'sixth': 5
+- 'seventh': 6
+- 'eighth': 7
+- 'last': -1
+- 'second_to_last': -2
+- 'third_to_last': -3
+- 'fourth_to_last': -4
+- 'fifth_to_last': -5
+- 'sixth_to_last': -6
+- 'seventh_to_last': -7
+- 'eighth_to_last': -8
+
+Order relative to other tests
+-----------------------------
 The test order can be defined relative to other tests, which are referenced
 by their name:
 
@@ -222,9 +245,12 @@ by their name:
 
     =========================== 4 passed in 0.02 seconds ===========================
 
+Configuration
+=============
+Currently there is only one option that changes the behavior of the plugin.
+
 ``--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
@@ -239,7 +265,6 @@ pytest-order *before* the sort from ``--failed-first``, allowing the failed
 tests to be sorted to the front.
 
 
-
 .. toctree::
    :maxdepth: 2