Documentation improvements

[Zethson]

First set of suggested changes to improve documentation.

• Uses correct admonition syntax - however this breaks the Github README sigh
• Renames notebooks to tutorials
• Minor fixes

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.06%. Comparing base (352f4f8) to head (582b318).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #130      +/-   ##
==========================================
- Coverage   93.71%   91.06%   -2.65%     
==========================================
  Files          10       10              
  Lines         795      795              
==========================================
- Hits          745      724      -21     
- Misses         50       71      +21     

see 3 files with indirect coverage changes

🚀 New features to boost your workflow:

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

[Zethson]

@ilan-gold I just noticed that the current admonition style works for Github READMEs but breaks for the myst based rendered docs. I think the only reasonable solution is to not include the whole README to use the right syntax at the right place. In other words, I'd slim down the README and move that content into a different place. WDYT?

[ilan-gold]

@ilan-gold I just noticed that the current admonition style works for Github READMEs but breaks for the myst based rendered docs. I think the only reasonable solution is to not include the whole README to use the right syntax at the right place. In other words, I'd slim down the README and move that content into a different place. WDYT?

@felix0097 has in the past been quite adamant about having the README be a bit self-contained. I think the admonition syntax not working there is a reasonable price to pay TBH

[ilan-gold]

Ideally we'd have a converted between the two (theoretically not a bad idea for scanpydoc actually)