Improve formatting of examples, better section separation, and point README to examples

[mborland]

Closes: #1240
Closes: #1241

[cppalliance-bot]

An automated preview of the documentation is available at https://1242.decimal.prtest3.cppalliance.org/libs/decimal/doc/html/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2025-11-13 13:22:51 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.0%. Comparing base (51b8ddb) to head (6e75d0b).
⚠️ Report is 16 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #1242   +/-   ##
=======================================
  Coverage     99.0%   99.0%           
=======================================
  Files          264     264           
  Lines        17251   17251           
  Branches      1931    1931           
=======================================
  Hits         17078   17078           
  Misses         173     173           

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 51b8ddb...6e75d0b. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.