[BUG] Fix redirect-from Sphinx extension (matplotlib#27915)

* [BUG] Fix clear_doc for redirect-from domain

* [BUG] Implement merge_domaindata

Update merge_domaindata to match Sphinx example implementation
https://github.com/sphinx-doc/sphinx/blob/5523c9bbe4d1415777669330411d4f00ad802f18/sphinx/ext/todo.py#L90-L92

* [BUG] Remove check for redirects that already exist

Check causes build to fail when Sphinx uses a cached build environment. We can just rewrite the cached redirect.

* [LINT] Fix linting issue

* [ENH] Switch Directive to SphinxDirective, which has self.env

* [BUG] Re-introduce sanity check

* Added domain.redirects sanity check back in
* Clear cached redirects from the domain

* [BUG] Reintroduce merge_domaindata sanity check

* Refactor

* Revert changes to merge_domaindata

* Cleanup code

Implement suggested changes

Co-authored-by: Elliott Sales de Andrade <[email protected]>

---------

Co-authored-by: Elliott Sales de Andrade <[email protected]>

Author: trananso

doc/sphinxext/redirect_from.py

@@ -33,7 +33,7 @@
 """
 
 from pathlib import Path
-from docutils.parsers.rst import Directive
+from sphinx.util.docutils import SphinxDirective
 from sphinx.domains import Domain
 from sphinx.util import logging
 
@@ -51,9 +51,9 @@
 
 
 def setup(app):
-    RedirectFrom.app = app
     app.add_directive("redirect-from", RedirectFrom)
     app.add_domain(RedirectFromDomain)
+    app.connect("builder-inited", _clear_redirects)
     app.connect("build-finished", _generate_redirects)
 
     metadata = {'parallel_read_safe': True}
@@ -73,8 +73,8 @@ def redirects(self):
         """The mapping of the redirects."""
         return self.data.setdefault('redirects', {})
 
-    def clear_doc(self, docnames):
-        self.redirects.clear()
+    def clear_doc(self, docname):
+        self.redirects.pop(docname, None)
 
     def merge_domaindata(self, docnames, otherdata):
         for src, dst in otherdata['redirects'].items():
@@ -86,15 +86,14 @@ def merge_domaindata(self, docnames, otherdata):
                     f"{self.redirects[src]} and {otherdata['redirects'][src]}")
 
 
-class RedirectFrom(Directive):
+class RedirectFrom(SphinxDirective):
     required_arguments = 1
 
     def run(self):
         redirected_doc, = self.arguments
-        env = self.app.env
-        domain = env.get_domain('redirect_from')
-        current_doc = env.path2doc(self.state.document.current_source)
-        redirected_reldoc, _ = env.relfn2path(redirected_doc, current_doc)
+        domain = self.env.get_domain('redirect_from')
+        current_doc = self.env.path2doc(self.state.document.current_source)
+        redirected_reldoc, _ = self.env.relfn2path(redirected_doc, current_doc)
         if redirected_reldoc in domain.redirects:
             raise ValueError(
                 f"{redirected_reldoc} is already noted as redirecting to "
@@ -119,3 +118,10 @@ def _generate_redirects(app, exception):
             logger.info('making refresh html file: %s redirect to %s', k, v)
             p.parent.mkdir(parents=True, exist_ok=True)
             p.write_text(html, encoding='utf-8')
+
+
+def _clear_redirects(app):
+    domain = app.env.get_domain('redirect_from')
+    if domain.redirects:
+        logger.info('clearing cached redirects')
+        domain.redirects.clear()