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
Open
Changes from all commits
Commits
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
21 changes: 14 additions & 7 deletions doc/format.rst
Original file line number Diff line number Diff line change
Expand Up @@ -753,18 +753,25 @@ 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.
- For example, module, class, function, method, and attribute names
should be enclosed in single backticks. On a case-by-case basis,
instances may also be included in single backticks, like :py:obj:`None`,
:py:obj:`True`, :py:obj:`False`.

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
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 +772 to +773
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