sphinx.ext.extlinks: Allow Callback for URL Format String

[shimizukawa]

It would be nice if instead of a formatting string, you could pass a callable that returns the combined URL for extlinks. This would allow cases where the input part isn't quite part of the url.

For example, this Docker reference uses lowercase anchors, but uppercase section titles: https://docs.docker.com/reference/builder/

Here's my current extlinks config:

    'Dockerfile': (
        'https://docs.docker.com/reference/builder/#%s',
        ''
    )

To handle the difference in captalization, I need to link as follows:

:Dockerfile:`RUN <run>`

It would be preferable to define the extlink using a callable handling the case conversion:

    'Dockerfile': (
        lambda part: 'https://docs.docker.com/reference/builder/#%s' % part.lower(),
        ''
    )

I suspect this is one of many possible use cases that would benefit. And since you could test for a callable vs a string, it should be fully backwards compatible.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1622
• Originally reported by: Kevin Stone
• Originally created at: 2014-11-09T18:38:07.878

[AA-Turner]

@abathur -- thank you for the PR!

After thinking a little, I'm not sure callback functions in conf.py are the best way to go, as it makes it harder for a future static configuration file.

I wonder if adopting a regex based approach would work? In the motivating example in this issue is changing uppercase to lowercase, which could potentially be done with a regex-inspired syntax?

A

[abathur]

FWIW, here's a TODO I left for myself where I encountered the desire for this:

"wiki_p": ("https://en.wikipedia.org/wiki/%s", None),
# TODO: technically we could try to internationalize wiki links 
# with something like below, but it would only work when the 
# term is the same. This may be true for some proper nouns 
# and more recent concepts, but there will almost certainly be 
# exceptions. It would be nice to use a callable here to map 
# English entry names to other languages (but fall back on 
# English entries whenever one is missing.)
# "wiki_p": ('https://{}.wikipedia.org/wiki/%s'.format(app.config.language), None)