docs: fix merge order in the config how-to (#529)

The example under "Merging config from multiple sources" merges in the
wrong direction. Its comment claims it iterates "from least specific
(site) to most specific (user)", but the iterators yield the user
directory first:

```pycon
>>> list(PlatformDirs("MyApp").iter_config_paths())
[PosixPath('/Users/me/Library/Application Support/MyApp'), PosixPath('/Library/Application Support/MyApp')]
```

So `config.update()` applies the site file last and the site defaults
overwrite the user's own config, the opposite of what the paragraph
above the block promises.

With a site `config.json` of `{"theme": "site-default", "lang": "en"}`
and a user one of `{"theme": "user-choice"}`, the documented loop yields
`theme: site-default`. Reversing it yields `theme: user-choice` and
still inherits `lang` from the site file.

Found while reviewing #524, which cites this example as the use case its
iterators serve. Docs only, no behaviour change.

Author: gaborbernat

docs/changelog/529.doc.rst

@@ -0,0 +1,2 @@
+Fix the config merging example in the how-to guide. ``iter_config_paths`` yields the user directory first, so the
+``config.update`` loop let the site defaults override the user's config instead of the other way round.

docs/howto.rst

@@ -143,8 +143,8 @@ user-specific overrides:
     dirs = PlatformDirs("MyApp")
     config = {}
 
-    # Iterate from least specific (site) to most specific (user)
-    for config_dir in dirs.iter_config_paths():
+    # The iterators yield the user directory first, so apply them in reverse to let it win
+    for config_dir in reversed(list(dirs.iter_config_paths())):
         config_file = config_dir / "config.json"
         if config_file.exists():
             config.update(json.loads(config_file.read_text()))

tests/test_api.py

@@ -141,3 +141,10 @@ def test_mypy_subclassing() -> None:
     class PlatformDirsSubclass(platformdirs.PlatformDirs): ...
 
     class AppDirsSubclass(platformdirs.AppDirs): ...
+
+
+@pytest.mark.parametrize("kind", ["config", "data", "cache", "state", "log", "runtime"])
+def test_iter_dirs_yields_user_before_site(kind: str) -> None:
+    # docs/howto.rst merges config in reverse of this order so the user directory wins.
+    dirs = platformdirs.PlatformDirs("MyApp", "MyCompany", version="1.0")
+    assert next(getattr(dirs, f"iter_{kind}_dirs")()) == getattr(dirs, f"user_{kind}_dir")