docs: document set_log_path() usage and hook examples

[Anurag-M1]

Description

This PR improves the documentation for set_log_path() in doc/en/how-to/logging.rst, resolving #8086.

Currently, the documentation notes that set_log_path() can be called to customize the log_file path dynamically, but does not explain how to access the method or provide hook examples.

This change:

• Clarifies that set_log_path() is a method on the LoggingPlugin instance, retrievable via config.pluginmanager.get_plugin("logging-plugin").
• Adds a pytest_configure hook example for generating dynamic, timestamped session log files, highlighting the need for @pytest.hookimpl(trylast=True).
• Adds a pytest_runtest_setup hook wrapper example for recording per-test log files.
• Notes that parent directories are created automatically if they do not exist.
• Adds changelog/8086.doc.rst and updates AUTHORS.

Closes #8086.

Checklist

• Documentation added / updated.
• Documentation verified with sphinx-build -W --keep-going.
• Linters and formatting verified with pre-commit.
• Existing tests verified (testing/logging/test_reporting.py).
• Changelog entry added in changelog/8086.doc.rst.
• Added name to AUTHORS in alphabetical order.
• Allow maintainers to push and squash when merging my commits.

[LaTranquillum]

The per-item example in doc/en/how-to/logging.rst:283 can overwrite an earlier test's log because item.name is not unique across modules.

Using the PR's pytest_runtest_setup hook unchanged in conftest.py, these two files reproduce the problem:

# test_a.py
import logging

def test_same():
    logging.warning("UNIQUE_MESSAGE_A")

# test_b.py
import logging

def test_same():
    logging.warning("UNIQUE_MESSAGE_B")

On CPython 3.14.2 / pytest 9.1.1 / macOS, running PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q test_a.py test_b.py reports 2 passed, but the only file, logs/test_same.log, contains only UNIQUE_MESSAGE_B. With the default write mode, the second call to set_log_path() truncates the first test's log.

Could the example derive a filesystem-safe filename from the full item.nodeid instead? For example, using sha256(item.nodeid.encode()).hexdigest() as the filename stem preserved two separate files containing the respective messages in the same reproduction. That requires from hashlib import sha256. Append mode alone would combine the logs rather than provide the advertised separate file per test item.

Validation was limited to these two tests with the original example and the same two tests with the changed filename (four test executions); no full suite or docs build was run.

Disclosure: Codex assisted with the investigation, ran the local reproductions, and drafted this feedback; I reviewed the finding and authorized submission.

[Anurag-M1]

Good catch, thanks for the clear reproduction!

I have updated the pytest_runtest_setup example in doc/en/how-to/logging.rst to derive the log filename stem using sha256(item.nodeid.encode()).hexdigest(). This ensures the filename is unique across modules, classes, and parameterizations while remaining safe on all filesystems:

from hashlib import sha256
from pathlib import Path
import pytest


@pytest.hookimpl(wrapper=True, tryfirst=True)
def pytest_runtest_setup(item: pytest.Item):
    logging_plugin = item.config.pluginmanager.get_plugin("logging-plugin")
    if logging_plugin is not None:
        # item.nodeid uniquely identifies each test; hashing avoids
        # filesystem-unsafe characters (such as "::" or parameters).
        log_name = sha256(item.nodeid.encode()).hexdigest()
        log_file = Path(item.config.rootpath) / "logs" / f"{log_name}.log"
        logging_plugin.set_log_path(str(log_file))
    return (yield)