Makefile help / moving examples.

Author: hans-d

Makefile

@@ -1,13 +1,16 @@
 .PHONY: clean-pyc clean-build docs clean
 
 help:
+	@echo "clean        Lint, test, check coverage and package"
 	@echo "clean        Remove all build, test, coverage and Python artifacts"
 	@echo "clean-build  Remove build artifacts"
 	@echo "clean-pyc    Remove Python file artifacts"
 	@echo "clean-test   Remove test and coverage artifacts"
 	@echo "lint         Check style with Flake8 and Pylint"
-	@echo "test         Run tests quickly with Python 3.11"
-	@echo "test-all     Run tests on every Python version with tox"
+	@echo "test         Run quick tests and those for the example code"
+	@echo "test-quick   Run tests quickly (main code only)with Python 3.11"
+	@echo "test-example Run tests for the example code"
+	@echo "test-all     Run tests on every Python version with tox and the example"
 	@echo "coverage     Check code coverage quickly with Python 3"
 	@echo "dist         Package"
 
@@ -31,7 +34,7 @@ clean-test:
 	rm -f .coverage
 	rm -fr htmlcov/
 
-all: lint test-all coverage dist readme
+all: lint test-all coverage dist
 
 lint:
 	tox -e lint

README.rst

@@ -85,16 +85,14 @@ Upgrade to 3.0
 Version 3 now uses `tmp_path`_, resulting in `pathlib.Path` objects
 instead of `py.path`.
 
-Your tests may need to be adjusted.
-
-.. literalinclude:: tests/examples/example_upgradev3.py
-    :language: python
+Your tests may need to be adjusted. In `examples/example_upgradev3.py` you see some possible
+variations.
 
 
 Usage
 -----
 
-These examples can also be found in `tests/examples`.
+The full code with more details for the examples can be found in `examples/`.
 
 Example 1
 ~~~~~~~~~
@@ -105,8 +103,14 @@ large video files stored under */opt/big_files/* . You don't want your tests mod
 the original files, but the files are required by the tests. You can reference these
 data files in your test method as follows:
 
-.. literalinclude:: tests/examples/example_1.py
-    :language: python
+.. code-block:: python
+
+    # more details in `examples/example_1.py`
+
+    @pytest.mark.datafiles('/opt/big_files/film1.mp4')
+    def test_fast_forward(datafiles):
+        # ...
+
 
 Example 2
 ~~~~~~~~~
@@ -116,17 +120,39 @@ place a directory named *test_files*. Here you have a lot of images you want to
 on. By using this plugin, you make sure the original files under *test_files* are not
 modified by every test.
 
-.. literalinclude:: tests/examples/example_2.py
-    :language: python
+.. code-block:: python
+
+    # more details in `examples/example_2.py`
+
+    @pytest.mark.datafiles(
+        FIXTURE_DIR / 'img1.jpg',
+        FIXTURE_DIR / 'img2.jpg',
+        FIXTURE_DIR / 'img3.jpg',
+    )
+    def test_find_borders(datafiles):
+        # ...
+
 
 Example 3
 ~~~~~~~~~
 
 If all (or many) of your tests rely on the same files it can be easier to
 define one decorator beforehand and apply it to every test like this example:
 
-.. literalinclude:: tests/examples/example_3.py
-    :language: python
+.. code-block:: python
+
+    # more details in `examples/example_3.py`
+
+    ALL_IMGS = pytest.mark.datafiles(
+        FIXTURE_DIR / 'img1.jpg',
+        FIXTURE_DIR / 'img2.jpg',
+        FIXTURE_DIR / 'img3.jpg',
+    )
+
+    @ALL_IMGS
+    def test_something1(datafiles):
+        # ...
+
 
 Example 4
 ~~~~~~~~~
@@ -136,16 +162,23 @@ Imagine you have 3 directories (*dir1*, *dir2*, *dir3*) each containing the file
 
 This example clarifies the options **on_duplicate** and **keep_top_dir**.
 
-.. literalinclude:: tests/examples/example_4.py
-    :language: python
 
 Example 5
 ~~~~~~~~~
 
 You can also use a str paths.
 
-.. literalinclude:: tests/examples/example_5.py
-    :language: python
+.. code-block:: python
+
+    # more details in `examples/example_5.py`
+
+    @pytest.mark.datafiles(
+        os.path.join(FIXTURE_DIR, 'img1.jpg'),
+        os.path.join(FIXTURE_DIR, 'img2.jpg'),
+        os.path.join(FIXTURE_DIR, 'img3.jpg'),
+    )
+    def test_str(datafiles):
+        # ...
 
 
 Contributing

tests/examples/_fixture_files/dir1/fileA renamed to examples/_fixture_files/dir1/fileA

@@ -1,4 +1,11 @@
-"""Example: Reference files anywhere """
+"""Example: Reference files anywhere.
+
+One possible use case is when you are running tests on very big files that are
+not included or packaged with your tests. For example, your test files are
+large video files stored under */opt/big_files/* . You don't want your tests
+modifying the original files, but the files are required by the tests.
+
+"""
 import os
 import pytest
 

tests/examples/_fixture_files/dir1/fileB renamed to examples/_fixture_files/dir1/fileB

@@ -1,4 +1,11 @@
-"""Example: make a subset of the files in a dir available."""
+"""Example: make a subset of the files in a dir available.
+
+Now for another use case: let's say in the directory where your tests are
+located, you place a directory named *test_files*. Here you have a lot of
+images you want to run tests on. By using this plugin, you make sure the
+original files under *test_files* are not modified by every test.
+
+"""
 from pathlib import Path
 
 import pytest