New feature: linking to source files at arbitrary URLs

[Lucas-C]

Hi.

Feature request

Would it be possible to generate links to source files in arbitrary git repositories (GitHub, Gitlab....)
when inserting doxygen* directives?

Feature proposal

A new optional breathe configuration setting:

breathe_file_src_url = "https://github.com/breathe-doc/breathe/blob/master/{file_path}#L{line}"

Demo

I submitted a monkey-patch based solution in this PR on a project using breathe: motis-project/utl#30

Resulting documentation: https://motis-project.github.io/utl/#api-details

Relevant code in conf.py:

html_theme = 'sphinx_rtd_theme'
html_theme_options = {
    'style_external_links': True,
}

from pathlib import Path
from docutils import nodes
from breathe.renderer.sphinxrenderer import SphinxRenderer

breathe_file_src_url = "https://github.com/motis-project/utl/blob/master/{file_path}#L{line}"
REPO_ROOT_DIR = Path(__file__).parent.parent

def create_doxygen_target(self, node):
    loc = node.location
    file_path = loc.file[len(str(REPO_ROOT_DIR))+1:]
    url = breathe_file_src_url.format(file_path=file_path, line=loc.line)
    title = f"{file_path} on line {loc.line}"
    return [nodes.reference("", "", refuri=url, reftitle=title)]

# Monkey patching this method:
SphinxRenderer.create_doxygen_target = create_doxygen_target

Extract from index.md (this project uses Markdown instead of reStructuredText):

:::{doxygenstruct} utl::log
:no-link:
:members:
:::

Notes

Related issues

• Breathe doesn't support external documentation (eg: tagfiles) #328

Implementation

This solution uses .reference.external HTML <a> links,
in combination with the :no-link: option
and style_external_links=True in the theme used.

A cleaner solution could be to use the definition (🔗) links instead,
that are inserted by default when no-link is not specified.

Also this implementation does not take care to distinguish links to source files from other kind of URLs
(e.g. generated by docurllink). Some care should be taken regarding this in the final implementation.