DOC: Extend explanation on single vs double backticks.

[Carreau]

Add the special case for constant, and try to separate semantic (can link), to style (monospace, link)

See also #525

[mdhaber]

I think the original sentence and this one focus on conceptualy distinct things.

• Things that link should be enclosed in single backticks.
• Things that are code should be rendered in monospaced font.

This exchanges one for the other. Maybe the best would be to more clearly distinguish between these two ideas and mention that often things that link are code, and links to objects appear in monospaced font, so in these cases single backticks take priority because they accomplish both.

[Carreau]

I think the original sentence and this one focus on conceptualy disting things.

• Things that link should be enclosed in single backticks.
• Things that are code should be rendered in monospaced font.

This exchanges one for the other. Maybe the best would be to more clearly distinguish between these two ideas and mention that often things that link are code, and links to objects appear in monospaced font, so in these cases single backticks take priority because they accomplish both.

But isn't that conflating again semantic and styling ? Say the community realize that double backticks is much better in blinking red, and link in rainbow underline italic ?

Can we find a way to drop any reference to the visual representation ? can we replace monospace by code sample ? The fact that it is monospace is again purely a css-theme thing (for html), and if you render in terminal well... everything is monospace.

[mdhaber]

Can we find a way to drop any reference to the visual representation

I think our motivations are different. I am actually interested in the particular visual representation. If there were some other visual cue that were to designate text as "code sample" and it were in proportional font, I would be motivated to suggest that it be in monospaced font.

I suppose if all IDEs and terminals began to use proportional font and chose some other way to designate code as code, my brain might change, too. But while unicode seems to be (is?) the universal convention for "this is code", I think our documentation should follow the convention, and I don't hesitate to refer to the appearance.

[stefanv]

We have a translation layer, in the form of numpydoc, so that we can define a format of our choice and render that however we want. So, I also lean towards focusing on the semantics, and then updating numpydoc accordingly.

E.g., while we are currently tightly coupled to sphinx, one can easily imagine a nearby future in which we render docs with papyri, or a combo of papyri and mystmd.

[Carreau]

I agree personally with @mdhaber wish for final style, but as numpydoc does not control the rendering, only the parsing, I think that using the style as the main reason is a weaker argument than semantic, because if a project disagrees on monospace, why would they follow single backticks and not use stars ? While if you recommend a semantic and note that this semantic is usually monospace, to do not give a reason for a project to deviate from but simply to change the theme.

Maybe we should get clearer distinction about recommended syntax and semantic. recommended formatting and style.

[Carreau]

Another argument against using the final monospace style, is that currently we all wish for both single backticks and double backticks to render as monospace font, the only difference being that single backtick will also be link to the relevant objects (or have a hover tooltip maybe ?) who knows.

So I think I find it weird because my brain reads the current proposal as "single backticks should be used for targets that will render as monospace, while you should use double backticks for code that should render monospace".

[mdhaber]

I guess this still says that things "typically" appear in monospace. Others have a better idea of the scope of numpydoc, so this is fine by me. Two last comments:

• It says "On a case-by-case basis, instances may also be included in single backticks, like :py:obj:None, :py:obj:True, :py:obj:False." Is "instances" synonymous with "literals"? Do we make any recommendation for them to be in double backticks if they are not to be linked, or is this out of scope?
• We mentioned "Module, class, function, method, and attribute names" but I forgot about returns. Should those get single backticks, too? They are sort of an interesting case because we give these labels to the returned values, but those labels don't necessarily appear in any code.