Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: Extend explanation on single vs double backticks. #565

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

Carreau
Copy link
Contributor

@Carreau Carreau commented Jun 11, 2024

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

See also #525

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

See also numpy#525
doc/format.rst Outdated
Comment on lines 756 to 758
- 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,
Copy link
Contributor

@mdhaber mdhaber Jun 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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,

Copy link
Contributor

@mdhaber mdhaber Jun 27, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines +773 to +774
- All other text that is intended to render in ``monospaced`` font and is not
supposed to refer to another docs page should be enclosed within ````double
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I'm happy to remove.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@mdhaber
Copy link
Contributor

mdhaber commented Jun 11, 2024

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.

Co-authored-by: Matt Haberland <mhaberla@calpoly.edu>
@Carreau
Copy link
Contributor Author

Carreau commented Jun 11, 2024

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
Copy link
Contributor

mdhaber commented Jun 11, 2024

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
Copy link
Contributor

stefanv commented Jun 11, 2024

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
Copy link
Contributor Author

Carreau commented Jun 12, 2024

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
Copy link
Contributor Author

Carreau commented Jun 12, 2024

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
Copy link
Contributor

mdhaber commented Jun 27, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants