rework sphinx documentation so we can both integrate API docs, and shove in module level overrides

[ferringb]

See https://github.com/pkgcore/snakeoil/blob/47d756214d27477d23bdbccca6a95b29d77345a7/src/snakeoil/deprecation.py ; the usage of this is actually straight forward. For snakeoil we create our project registry in _internals and then just do thus: https://github.com/pkgcore/snakeoil/commit/47d756214d27477d23bdbccca6a95b29d77345a7 . This annotates all of the deprecations we have- where we have a fixed terminus in mind. That registry retains those deprecations allowing a test that checks for expired deprecations and converts them into failures. That test base is https://github.com/pkgcore/snakeoil/blob/47d756214d27477d23bdbccca6a95b29d77345a7/src/snakeoil/test/code_quality.py#L124-L140

This is what enforces it for snakeoil code; https://github.com/pkgcore/snakeoil/blob/47d756214d27477d23bdbccca6a95b29d77345a7/src/snakeoil/test/code_quality.py#L124-L140

There's multiple layers here, but it's actually pretty simple to use: the module level documentation will not be sufficient for explaining how to use this since there is a pattern downstreams should implement.

TL;DR: the sphinx doc generation needs to be tweaked so we can handle this in a way like the python docs do.