Update rendering of docs, fix some docstrings

[pawamoy]

It uses some mkdocstrings-python insiders features 😀 (signature_crossrefs, show_symbol_type_heading and show_symbol_type_toc).

Let me know what you think, just had some fun trying latest mkdocstrings and mkdocstrings-python on your handler docs 😄

Also I've identified the problematic docstring sections with this:

% griffe dump -Ldebug -o/dev/null -fdgoogle mkdocstrings_handlers.crystal 2>&1 | grep reasons
DEBUG      mkdocstrings_handlers/crystal/items.py:87: Possible section skipped, reasons: Missing blank line above section
DEBUG      mkdocstrings_handlers/crystal/items.py:89: Possible section skipped, reasons: Missing blank line above section
DEBUG      mkdocstrings_handlers/crystal/items.py:469: Possible section skipped, reasons: Missing blank line above section

(latest Griffe is a bit more strict about section syntax, to avoid false-positives)

[pawamoy]

Sorry about this, VSCode auto-formatted it.

[oprypin]

Thanks.

Hm but to use insiders that will require some setup, the docs are generated on GitHub without insiders. Also not fully sure if I'm willing to use insiders in the first place

[pawamoy]

Yeah I can understand that, it complicates the setup. It was mostly to show you how it looked 😄

If you're interested in some of the other changes, edit my comment to check their boxes and I'll keep only those:

• CSS indentation and external links marker
• Importing mkdocstrings objects inventory
• Merging __init__ methods documentation into their parent class' docs
• Separating signature from the header

Or feel free to close the PR and do these things later, or never 😀

[pawamoy]

Closing, feel free to pick up any changes here in other commits/PRs 🙂