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 "for example" is more appropriate than "that is" here because it gives examples rather than restating. Also, I assume you meant "on a case-by-case basis"

Suggested change

	- Any object that can be linked to should be enclosed in single backticks. That
	is to say : Module, class, function, method, and attribute names are some of
	the objects that should be enclosed in single backticks. On a case by cases,
	- For example, module, class, function, method, and attribute names
	should be enclosed in single backticks. On a case-by-case basis,

[mdhaber]

Oops, I think I messed up here. Either these are the complete list of things we want to make a rule about (as it was originally) or these are a subset of a more general class of things to enclose in backticks. If these are a subset, then they are just examples of a rule, and I didn't mean to remove the rule: "Any object that can be linked to should be enclosed in single backticks."

[mdhaber]

I thought "and is not supposed to refer to another docs page" was implied because this says "All other text" and it appears after we've discussed links. Does it need to be more explicit?

[Carreau]

I think we can also be more explicit, and you can have monospaced linked to another page if you use a directive. like :ref:`the text <the_ref>` technically I think. I'm just also trying to separate rendering from semantic.

[Carreau]

But I'm happy to remove.

[mdhaber]

I read it as redundant, but if others don't, it's fine!

[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.