This ticket is to track the visual design of #454.

Current implementation

We simply use an external link on the same line as the code object's description. It always appears at the end of the code and is normal text - we don't do any funky floating or anything.

I suspect this design is probably fine other than weirdness with the padding. Note how the underline extends directly to the code. I couldn't fix this by adding extra whitespace in the content - it wouldn't work. I think we need to adjust the CSS.

But what is tricky about adjusting the CSS is it will impact all inline code highlighting:

Note that we're using padding-right for inline code, rather than margin-right, which would result in the background not being the shaded gray.

Original notes

What the old qiskit.org design looks like

When you click the [source] link, it takes you a new webpage on qiskit.org with a copy of the source code:

Our implementation will instead take you to GitHub.com, so be an external link.

Note how the old design handles the # icon to get the permalink for the current code object. This only happens on hover:

Which code objects have links?

Note that not every single code object has a link, For example, in the first image in this issue, only exception QiskitNatureError has it, but not its method with_traceback().

However, there are other places where methods do have their own link. (Methods are a lower information hierarchy than the class they belong to.)

So, I think the safest thing to design for is that both the top-level code object—like the class—and also the code objects one level lower—like methods—can have the link but they might not.

--

The link should probably show up on the same line as the name of the code object itself? But, it is common that the line will wrap:

Copy for the link

We discussed in a meeting that [source] might be vague. We only used that name with qiskit.org because it's what Sphinx itself uses and we can't easily change it.

For the new Qiskit docs, maybe we want something more explicit like [GitHub]? Or GitHub ↗?