docs: Rewrite Handling Paths chapter (pathlib vs utils)

[JOJ0]

Description

Updates the docs chapter "Handling Paths" describing how to modernise old code and intentionally includes historical details. Examples should further guide contributors while refactoring.

To Do

• Documentation. (If you've added a new command-line flag, for example, find the appropriate page under docs/ to describe it.)
• Changelog. (Add an entry to docs/changelog.rst to the bottom of one of the lists near the top of the document.)
• Tests. (Very much encouraged but not strictly required.)

[Copilot]

Pull Request Overview

This PR rewrites the "Handling Paths" chapter in the contributing documentation to reflect the transition from legacy path utilities (syspath(), normpath(), bytestring_path(), displayable_path()) to modern pathlib.Path. The documentation now includes historical context explaining why the old utilities existed, guidance on when to use each approach, and concrete examples showing old vs. new patterns.

• Adds historical context for legacy path utilities and their original purposes
• Introduces pathlib.Path as the preferred approach for new code
• Provides side-by-side examples comparing old and new path handling patterns

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Using resolve() in the example may be misleading as it canonicalizes the path by resolving symlinks and making it absolute, which differs from normpath()'s behavior. normpath() only normalized slashes and removed . and .. without resolving symlinks or making paths absolute. Consider using Path(...).expanduser() alone or clarifying that resolve() does more than the old normpath().

Suggested change

	Path("~/Music/../Artist").expanduser().resolve()
	Path("~/Music/../Artist").expanduser()

[sourcery-ai]

Hey there - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 66.98%. Comparing base (c26c342) to head (f59e521).
⚠️ Report is 11 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #6116   +/-   ##
=======================================
  Coverage   66.98%   66.98%           
=======================================
  Files         118      118           
  Lines       18189    18191    +2     
  Branches     3079     3079           
=======================================
+ Hits        12184    12186    +2     
- Misses       5345     5346    +1     
+ Partials      660      659    -1     

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[semohr]

How do we feel about moving this into the developer documentation? I don't think it should be included in the contribution guide.

[semohr]

Can we use the full .. code-block:: python blocks? Otherwise my editor wont pick up highlighting 😢

[JOJ0]

How do we feel about moving this into the developer documentation? I don't think it should be included in the contribution guide.

Good idea! I keep forgetting n starting to look for it there anyway!! 😂