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.

Sign up for GitHub

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 3 commits into
base: main
Choose a base branch
from
Open

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

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ed89d7f
DOC: Extend explanation on single vs double backticks.
Carreau Jun 11, 2024
db19b2c
Apply suggestions from code review
Carreau Jun 11, 2024
23297ef
Merge branch 'main' into link-single
mdhaber Feb 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions doc/format.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -753,18 +753,26 @@ monospaced font; in reST, *double* backticks are for ``monospaced font``,
whereas the behavior of single backticks is defined by the default role. This
leads to the following style recommendations:

- Module, class, function, method, and attribute names should render as
hyperlinks in monospaced font (e.g. :any:`numpy`); depending on project
settings, this may be accomplished simply be enclosing them in single
backticks. If the hyperlink does not render as intended, explicitly
include the appropriate role and/or namespace.
- 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 •
edited
Loading

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 •
edited
Loading

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

instances may also be included in single backticks, like :py:obj:`None`,
:py:obj:`True`, :py:obj:`False`.
Comment on lines +760 to +761
Copy link
Contributor

Choose a reason for hiding this comment

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

@Carreau this renders like:
image

Seeing only the rendered version and not the underlying reST, I would assume from the text that these object names only need to be included in single backticks to render like this, but that's not quite right. Should these go at the end of the paragraph, after the idea of explicitly including the role and/or namespace is mentioned?


These will typically render as hyperlinks in monospaced font (e.g.
:any:`numpy`) to the relevant object documentation; depending on project
settings. If the hyperlink does not render properly or point to the intended
Comment on lines +764 to +765
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
:any:`numpy`) to the relevant object documentation; depending on project
settings. If the hyperlink does not render properly or point to the intended
:any:`numpy`) to the relevant object documentation.
If the hyperlink does not render properly or point to the intended

Semicolon is no longer the appropriate punctuation, and I think this part can just be removed now.

object, explicitly include the appropriate role and/or namespace.

- This guide continues to recommended that parameter names be enclosed within
single backticks. Currently, this may cause parameter names to render
improperly and cause warnings, but numpydoc will soon release a feature
that causes them to render as monospaced hyperlinks to the parameter
documentation.
- All other text that is intended to render in ``monospaced`` font should be
enclosed within ````double backticks````.

- 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
Comment on lines +774 to +775
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!

backticks````.

A more extensive example of reST markup can be found in `this example
document <http://docutils.sourceforge.net/docs/user/rst/demo.txt>`_;
Expand Down
Loading