A few docstring edits and documentation update

Author: Sylvain MARIE

docs/api_reference.md

@@ -239,3 +239,65 @@ Lists all desired cases for a given user query. This function may be convenient
  - `this_module_object`: any variable defined in the module of interest, for example a function. It is used to find "this module", when `module` contains `THIS_MODULE`. 
  - `has_tag`: an optional tag used to filter the cases in the `module`. Only cases with the given tag will be selected.
  - `filter`: an optional filtering function taking as an input a list of tags associated with a case, and returning a boolean indicating if the case should be selected. It will be used to filter the cases in the `module`. It both `has_tag` and `filter` are set, both will be applied in sequence.
+
+
+## 3 - Pytest goodies
+
+### `@pytest_fixture_plus`
+
+`pytest_fixture_plus(scope="function", autouse=False, name=None, **kwargs)`
+
+Identical to `@pytest.fixture` decorator, except that it supports multi-parametrization with `@pytest.mark.parametrize` as requested in [pytest#3960](https://github.com/pytest-dev/pytest/issues/3960).
+
+As a consequence it does not support the `params` and `ids` arguments anymore.
+
+### `fixture_union`
+
+`fixture_union(name, fixtures, scope="function", idstyle='explicit',
+               ids=fixture_alternative_to_str, autouse=False, **kwargs)
+               -> <Fixture>`
+
+Creates a fixture that will take all values of the provided fixtures in order. That fixture is automatically registered into the callers' module, but you may wish to assign it to a variable for convenience. In that case make sure that you use the same name, e.g. `a = fixture_union('a', ['b', 'c'])`
+
+The style of test ids corresponding to the union alternatives can be changed with `idstyle`. Three values are allowed:
+
+ - `'explicit'` (default) favors readability,
+ - `'compact'` adds a small mark so that at least one sees which parameters are union parameters and which others are normal parameters,
+ - `None` does not change the ids.    
+
+**Parameters:**
+
+ - `name`: the name of the fixture to create
+ - `fixtures`: an array-like containing fixture names and/or fixture symbols
+ - `scope`: the scope of the union. Since the union depends on the sub-fixtures, it should be smaller than the smallest scope of fixtures referenced.
+ - `idstyle`: The style of test ids corresponding to the union alternatives. One of `'explicit'` (default), `'compact'`, or `None`.
+ - `ids`: as in pytest. The default value returns the correct fixture
+ - `autouse`: as in pytest
+ - `kwargs`: other pytest fixture options. They might not be supported correctly.
+
+**Outputs:** the new fixture. Note: you do not need to capture that output in a symbol, since the fixture is automatically registered in your module. However if you decide to do so make sure that you use the same name.
+
+### `param_fixtures`
+
+`param_fixtures(argnames, argvalues, autouse=False, ids=None, scope="function", **kwargs)`
+
+Creates one or several "parameters" fixtures - depending on the number or coma-separated names in `argnames`. The created fixtures are automatically registered into the callers' module, but you may wish to assign them to variables for convenience. In that case make sure that you use the same names, e.g. `p, q = param_fixtures('p,q', [(0, 1), (2, 3)])`.
+
+
+Note that the `(argnames, argvalues, ids)` signature is similar to `@pytest.mark.parametrize` for consistency, see https://docs.pytest.org/en/latest/reference.html?highlight=pytest.param#pytest-mark-parametrize
+
+
+### `param_fixture`
+
+`param_fixture(argname, argvalues, autouse=False, ids=None, scope="function", **kwargs)`
+
+Identical to `param_fixtures` but for a single parameter name, so that you can assign its output to a single variable.
+
+
+### `@pytest_parametrize_plus`
+
+`pytest_parametrize_plus(argnames, argvalues, indirect=False, ids=None, scope=None, **kwargs)`
+
+Equivalent to `@pytest.mark.parametrize` but also supports the fact that in argvalues one can include references to fixtures with `fixture_ref(<fixture>)` where <fixture> can be the fixture name or fixture function.
+
+When such a fixture reference is detected in the argvalues, a new function-scope fixture will be created with a unique name, and the test function will be wrapped so as to be injected with the correct parameters. Special test ids will be created to illustrate the switching between normal parameters and fixtures.

docs/index.md

@@ -8,6 +8,10 @@
 
 !!! success "New `fixture_union` and `@pytest_parametrize_plus` are there, [check them out](#fixture_union) !"
 
+!!! warning "Test execution order"
+    Installing pytest-cases now has effects on the order of `pytest` tests execution, even if you do not use its features. One positive side effect is that it fixed [pytest#5054](https://github.com/pytest-dev/pytest/issues/5054). But if you see less desirable ordering please [report it](https://github.com/smarie/python-pytest-cases/issues).
+
+
 Did you ever thought that most of your test functions were actually *the same test code*, but with *different data inputs* and expected results/exceptions ?
 
 `pytest-cases` leverages `pytest` and its great `@pytest.mark.parametrize` decorator, so that you can **separate your test cases from your test functions**. For example with `pytest-cases` you can now write your tests with the following pattern:
@@ -235,7 +239,7 @@ def test_uses_param2(arg1, arg2, fixture_uses_param2):
 
 As of `pytest` 4, it is not possible to create a "union" fixture, i.e. a parametrized fixture that will first take all the possible values of fixture A, then all possible values of fixture B, etc. 
 
-The topic has been largely discussed in [pytest-dev](https://github.com/pytest-dev/pytest/issues/349) and a [request for proposal](https://docs.pytest.org/en/latest/proposals/parametrize_with_fixtures.html) has been finally made.
+The topic has been largely discussed in [pytest-dev#349](https://github.com/pytest-dev/pytest/issues/349) and a [request for proposal](https://docs.pytest.org/en/latest/proposals/parametrize_with_fixtures.html) has been finally made.
 
 `fixture_union` is an implementation of this proposal.
 
@@ -260,14 +264,13 @@ def test_basic_union(c):
 yields
 
 ```
-<...>::test_basic_union[first] hello
-PASSED
-<...>::test_basic_union[second-a] a
-PASSED
-<...>::test_basic_union[second-b] b
-PASSED
+<...>::test_basic_union[c_is_first] hello   PASSED
+<...>::test_basic_union[c_is_second-a] a    PASSED
+<...>::test_basic_union[c_is_second-b] b    PASSED
 ```
 
+As you can see the ids of union fixtures are slightly different from standard ids, so that you can easily understand what is going on. You can change this feature with `ìdstyle`, see [API documentation](./api_reference.md#fixture_union) for details.
+
 This feature has been tested in very complex cases (several union fixtures, fixtures that are not selected by a given union but that is requested by the test function, etc.). But if you find some strange behaviour don't hesitate to report it in the [issues](https://github.com/smarie/python-pytest-cases/issues) page !
 
 **IMPORTANT** if you do not use `@pytest_fixture_plus` but only `@pytest.fixture`, then you will see that your fixtures are called even when they are not used, with a parameter `NOT_USED`. This symbol is automatically ignored if you use `@pytest_fixture_plus`, otherwise you have to handle it.
@@ -307,17 +310,20 @@ yields the following
 
 ```bash
 > pytest -s -v
-nothing?
-nothing!
-world?
-world!
-hello world?
-hello world!
-hello you?
-hello you!
+collected 9 items
+test_prints[test_prints_main_msg_is_0-nothing-?] nothing?                                 PASSED
+test_prints[test_prints_main_msg_is_0-nothing-!] nothing!                                 PASSED
+test_prints[test_prints_main_msg_is_world_str-?] world?                                   PASSED
+test_prints[test_prints_main_msg_is_world_str-!] world!                                   PASSED
+test_prints[test_prints_main_msg_is_greetings-greetings_who_is_world_str-?] hello world?  PASSED
+test_prints[test_prints_main_msg_is_greetings-greetings_who_is_world_str-!] hello world!  PASSED
+test_prints[test_prints_main_msg_is_greetings-greetings_who_is_1-you-?] hello you?        PASSED
+test_prints[test_prints_main_msg_is_greetings-greetings_who_is_1-you-!] hello you!        PASSED
 ```
 
-Note: for this to be performed, the parameters are replaced with a union fixture. Therefore the relative priority order with standard 'mark' parameters will get impacted. You may solve this by replacing your mark parameters with `param_fixture`s (see [above](#param_fixtures).)
+As you can see, the ids are a bit more explicit than usual. As opposed to `fixture_union`, the style of these ids is not configurable for now but feel free to propose alternatives in the [issues page](https://github.com/smarie/python-pytest-cases/issues).
+
+Note: for this to be performed, the parameters are replaced with a union fixture. Therefore the relative priority order of these parameters with other standard `pytest.mark.parametrize` parameters that you would place on the same function, will get impacted. You may solve this by replacing your mark parameters with `param_fixture`s (see [above](#param_fixtures).)
 
 ## Main features / benefits
 

pytest_cases/main_fixtures.py

@@ -45,7 +45,8 @@
 
 def param_fixture(argname, argvalues, autouse=False, ids=None, scope="function", **kwargs):
     """
-    Identical to `param_fixtures` but for a single parameter name.
+    Identical to `param_fixtures` but for a single parameter name, so that you can assign its output to a single
+    variable.
 
     :param argname: see fixture `name`
     :param argvalues: see fixture `params`
@@ -149,7 +150,10 @@ def check_name_available(module,
 
 def param_fixtures(argnames, argvalues, autouse=False, ids=None, scope="function", **kwargs):
     """
-    Creates one or several "parameters" fixtures - depending on the number or coma-separated names in `argnames`.
+    Creates one or several "parameters" fixtures - depending on the number or coma-separated names in `argnames`. The
+    created fixtures are automatically registered into the callers' module, but you may wish to assign them to
+    variables for convenience. In that case make sure that you use the same names, e.g.
+    `p, q = param_fixtures('p,q', [(0, 1), (2, 3)])`.
 
     Note that the (argnames, argvalues, ids) signature is similar to `@pytest.mark.parametrize` for consistency,
     see https://docs.pytest.org/en/latest/reference.html?highlight=pytest.param#pytest-mark-parametrize