linkcheck: add HyperlinkCollector.find_url()

[jdknight]

Feature or Bugfix

• Refactoring

Purpose

The following tweaks the linkcheck builder's HyperlinkCollector transform to process links with an add_uri method on the transform (over an internal function inside the implementation). This can allow extensions to derive and register additional transforms using HyperlinkCollector to help inject hyperlinks into CheckExternalLinksBuilder for custom node types that may have a hyperlink value to check.

Details

While extensions can already override HyperlinkCollector to inject custom links, it needs to replicate some of the logic used to add a href value as a Hyperlink into a builder. This causes some duplication with emitting an event, line number finding and duplicate link checking. If the add_uri is available on the transform, extensions only need to care about finding the application refnode and href value.

Relates

• support linkcheck for confluence-specific href nodes sphinx-contrib/confluencebuilder#938

[picnixz]

I'm fine the idea but I would suggest the following:

• Have a dedicated method for retrieving the URI from the node (i.e., find_uri(self, node) -> str).
• Make add_uri a protected method (add a comment for that) and call it.

That way, you do not need to reimplement the whole method if you only need to find the URI from the node.

[jdknight]

@picnixz, just to make sure I understand your suggestions -- are you looking for something more like this?

class HyperlinkCollector(SphinxPostTransform):
    ...

    def run(self, **kwargs: Any) -> None:
        for node in self.document.findall():
            uri = self.find_uri(node)
            if uri:
                self._add_uri(uri, node)

    def find_uri(self, node: nodes.Element) -> Optional[str]:
        # reference nodes
        if isinstance(node, nodes.reference):
            if 'refuri' in node:
                return refnode['refuri']

        # image nodes
        if isinstance(node, nodes.image):
            uri = node['candidates'].get('?')
            if uri and '://' in uri:
                return uri

        # raw nodes
        if isinstance(node, nodes.raw):
            uri = node.get('source')
            if uri and '://' in uri:
                return uri

        return None

    def _add_uri(self, uri: str, node: nodes.Element) -> None:
        ...

[picnixz]

Yes, because it decouples the logic of what we already do and for extension developers, they can either subclass this method to extend the behaviour, possibly handling the images/raw nodes before and returning before as well (I think that's what you originally wanted, right?). Now, I won't be available for the next 2-3 weeks (or very sparsly), so I won't be able to review your PR until then.