Possible documentation improvements

[MateuszKubuszok]

This ticket is intended to be a pinned list of things that we can improve in the documentation. They might become full issues, they might be done as a part of another PR, they might be a good candidates for a contribution!

Latest stable documentation can be found at https://chimney.readthedocs.io/en/stable/ , latest master build can be found at https://chimney.readthedocs.io/en/latest/. Rendering it locally is described in CONTRIBUTION.md.

Things to improve

• some mini tutorial
  • simple user case with success
  • what happens on error
  • how to use the feedback to fix it
  • same for partials
  • and patchers
• ~explanation for optics-like uses cases - while we mentioned in Goals and non-goals that Chimney is NOT a lens library, with changes that happened over the last few versions (particularly around 1.0.0) it can be used to cover some cases that are typically within the lens domain~ - done in #583
• more good examples of Cats' integrations:
  • mapN/parMapN usage of Transformer/PartialTransformer/partial.Result
  • andThen/combine usage of Transformer/PartialTransformer/Codec/Iso
  • conversions to/from Chain/NonEmptyChain/NonEmptyList/NonEmptyVector/NonEmptySet...
• more good examples of Protobuf integrations:
  • ~example of .enableNonAnyValWrappers required to handle oneof value wrappers (single-element case classes storing sealed hierarchy)~ - done in #585
• adding comparisons with other popular mapping libraries (https://github.com/scalalandio/chimney/issues/350) and keeping existing ones up to date
• ~some section listing all flags/overrides in one place with links to their explanation~ - done as a part of #572
• ~some section explaining integrations package and AsResult type class~ - done in #584
• ~links to other tutorials~ - done in #585
  • ~https://www.youtube.com/watch?v=SNc7xeHrKnQ + https://mateuszkubuszok.github.io/DomainApiDtoChimney (newest example with Chimeny)~
  • ~https://mateuszkubuszok.github.io/ChimneyInternalsPresentation (Chimney under the hood examples with old macros)~
  • ~https://softwaremill.com/5-scala-libraries-that-will-make-your-life-easier/ (includes Chimney, as # 2)~
  • ~https://www.youtube.com/watch?v=ezz0BpEHEQY + https://youtu.be/ZymD5NuOwdA?si=P-4AnMiaIi2LVKVW~
  • ~https://www.youtube.com/watch?v=U67BAeH3cxo~
• in CONTRIBUTING.md
  • ~how to add OSS Sonatype snapshot repository to test~ - done as a part of #559
  • explain the missing coverage:
    • Scala 3 ignores $COVERAGE-OFF$
    • disableX flags are called only in compileErrors, so scoverage does not catch it
    • we were not using all of apply/unapply in type constructor although it's convenient to have them always available
    • some could be fixed OR ignores though
• last but not least: typos, erroneously put markdown tags, grammar fixes are always welcome!