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: 47d7562 . 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

snakeoil/src/snakeoil/test/code_quality.py

Lines 124 to 140 in 47d7562

	class ExpiredDeprecations(NamespaceCollector, still_abstract=True):
	strict_configurable_tests = ("test_has_expired_deprecations",)
	strict = ("test_has_expired_deprecations",)
	registry: deprecation.Registry = abstractclassvar(deprecation.Registry)
	version: deprecation.Version = abstractclassvar(deprecation.Version)
	python_minimum_version: deprecation.Version = abstractclassvar(deprecation.Version)
	def test_has_expired_deprecations(self, subtests):
	# force full namespace load to ensure all deprecations get registry.
	for _ in self.collect_modules():
	pass
	for deprecated in self.registry.expired_deprecations(
	self.version, self.python_minimum_version
	):
	with subtests.test(deprecated=str(deprecated)):
	pytest.fail(f"deprecation has expired: {deprecated}")

This is what enforces it for snakeoil code;

snakeoil/src/snakeoil/test/code_quality.py

Lines 124 to 140 in 47d7562

	class ExpiredDeprecations(NamespaceCollector, still_abstract=True):
	strict_configurable_tests = ("test_has_expired_deprecations",)
	strict = ("test_has_expired_deprecations",)
	registry: deprecation.Registry = abstractclassvar(deprecation.Registry)
	version: deprecation.Version = abstractclassvar(deprecation.Version)
	python_minimum_version: deprecation.Version = abstractclassvar(deprecation.Version)
	def test_has_expired_deprecations(self, subtests):
	# force full namespace load to ensure all deprecations get registry.
	for _ in self.collect_modules():
	pass
	for deprecated in self.registry.expired_deprecations(
	self.version, self.python_minimum_version
	):
	with subtests.test(deprecated=str(deprecated)):
	pytest.fail(f"deprecation has expired: {deprecated}")

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.