Document _path API

[adamchainz]

I was looking at the README wondering if you'd add a pathlib API, but then found it was done so in #27. The README could mention this :)

[gaborbernat]

This will be done part of #28

[adamchainz]

Great :)

[jaraco]

I recently started adopting app_paths because it promised pathlib support for appdirs. I later learned that platformdirs has superseded appdirs. I searched the readme and docs, but find no examples of getting pathlib objects, so here's one.

 ~ $ pip-run platformdirs
Python 3.11.1 (main, Dec 23 2022, 09:28:24) [Clang 14.0.0 (clang-1400.0.29.202)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import platformdirs
>>> dirs = platformdirs.AppDirs()
>>> dirs.user_cache_path
PosixPath('/Users/jaraco/Library/Caches')

[jaraco]

Also, adding something to the README referencing pathlib would have made it easier to discover this project for that purpose.

[gaborbernat]

I mean https://platformdirs.readthedocs.io/en/latest/api.html#platformdirs.user_cache_path ? Our README is not the docs.

[jaraco]

The term pathlib doesn't appear anywhere in the docs or the readme. I did search both before commenting. I do see now that the type annotations do indicate -> Path, but that wasn't nearly enough for me to realize that the functionality existed until I dived in to the code. Now that I realize it exists, it's easy to find, but discoverability could be improved.