Having a proper visually distinguishable box for admonitions would make it easier to read the documentations. Right now, we misuse markdown blockquotes and (sometime) use emojis for variants. But they are mixed in between other documentation paragraphs, that it is quite easy to miss (and does not look good to be honest).
Some screenshots where I found it confusing:
These are only a few examples that I quickly scanned through.
We can take some inspirations from spacy's and thinc's docs:
Having a proper visually distinguishable box for admonitions would make it easier to read the documentations. Right now, we misuse markdown blockquotes and (sometime) use emojis for variants. But they are mixed in between other documentation paragraphs, that it is quite easy to miss (and does not look good to be honest).
Some screenshots where I found it confusing:
These are only a few examples that I quickly scanned through.
We can take some inspirations from spacy's and thinc's docs:
