Hi!
Is there a culling of examples planned for 3.8.0? The mailing list has an ever-increasing number of mails that consist of "Don't use that, it's old and bad, use this shinier one". For people who are not familiar enough to already know, this just looks like black magic, which is something that is always needed less of.
An alternative would be a deprecation flag (or recommended versions) in basic_block, that could be modified, if a suggested replacement is introduced. That would then raise a warning at runtime, alerting early about potentially not future-proof design.
While doxygen has a category for deprecated blocks, the sphinx documentation does not (leaving aside that for most blocks, if you want to do anything you need to refer to the doxygen anyway)