Document record_property usage (#23)

Issue #7 document usage of `record_property` fixture

Author: soxofaan

.github/workflows/main.yml

@@ -25,9 +25,9 @@ jobs:
             tox_env: "py39"
 
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v3
     - name: Set up Python
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python }}
     - name: Install tox
@@ -43,9 +43,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v3
     - name: Set up Python
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v4
       with:
         python-version: "3.7"
     - name: Install tox
@@ -64,9 +64,9 @@ jobs:
     needs: [build, linting]
 
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v3
     - name: Set up Python
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v4
       with:
         python-version: "3.7"
     - name: Install wheel

README.rst

@@ -30,6 +30,8 @@ Replacement for the ``--resultlog`` option, focused in simplicity and extensibil
 Usage
 =====
 
+Install ``pytest-reportlog`` as a test requirement in your test environment.
+
 The ``--report-log=FILE`` option writes *report logs* into a file as the test session executes.
 
 Each line of the report log contains a self contained JSON object corresponding to a testing event,
@@ -91,6 +93,28 @@ The generated ``log.json`` will contain a JSON object per line:
     {"nodeid": "test_report_example.py::test_fail", "location": ["test_report_example.py", 4, "test_fail"], "keywords": {"test_fail": 1, "pytest-reportlog": 1, "test_report_example.py": 1}, "outcome": "passed", "longrepr": null, "when": "teardown", "user_properties": [], "sections": [], "duration": 0.0, "$report_type": "TestReport"}
     {"exitstatus": 1, "$report_type": "SessionFinish"}
 
+
+record_property
+---------------
+
+The ``record_property`` fixture allows to log additional information for a test, just like with JUnitXML format.
+Consider this test file:
+
+.. code-block:: python
+
+    def test_function(record_property):
+        record_property("price", 12.34)
+        record_property("fruit", "banana")
+        assert True
+
+This information will be recorded in the report JSON objects under the ``user_properties`` key as follows::
+
+    ..., "user_properties": [["price", 12.34], ["fruit", "banana"]], ...
+
+Note that this nested list construct is just the JSON representation
+of a list of tuples (name-value pairs).
+
+
 License
 =======