Skip to content

Commit ed89d7f

Browse files
committed
DOC: Extend explanation on single vs double backticks.
Add the special case for constant, and try to separate semantic (can link), to style (monospace, link) See also numpy#525
1 parent 58530b9 commit ed89d7f

File tree

1 file changed

+15
-7
lines changed

1 file changed

+15
-7
lines changed

doc/format.rst

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -753,18 +753,26 @@ monospaced font; in reST, *double* backticks are for ``monospaced font``,
753753
whereas the behavior of single backticks is defined by the default role. This
754754
leads to the following style recommendations:
755755

756-
- Module, class, function, method, and attribute names should render as
757-
hyperlinks in monospaced font (e.g. :any:`numpy`); depending on project
758-
settings, this may be accomplished simply be enclosing them in single
759-
backticks. If the hyperlink does not render as intended, explicitly
760-
include the appropriate role and/or namespace.
756+
- Any object that can be linked to should be enclosed in single backticks. That
757+
is to say : Module, class, function, method, and attribute names are some of
758+
the objects that should be enclosed in single backticks. On a case by cases,
759+
instances may also be included in single backticks, like :py:obj:`None`,
760+
:py:obj:`True`, :py:obj:`False`.
761+
762+
These will typically render as hyperlinks in monospaced font (e.g.
763+
:any:`numpy`) to the relevant object documentation; depending on project
764+
settings. If the hyperlink does not render properly or point to the intended
765+
object, explicitly include the appropriate role and/or namespace.
766+
761767
- This guide continues to recommended that parameter names be enclosed within
762768
single backticks. Currently, this may cause parameter names to render
763769
improperly and cause warnings, but numpydoc will soon release a feature
764770
that causes them to render as monospaced hyperlinks to the parameter
765771
documentation.
766-
- All other text that is intended to render in ``monospaced`` font should be
767-
enclosed within ````double backticks````.
772+
773+
- All other text that is intended to render in ``monospaced`` font and is not
774+
supposed to refer to another docs page should be enclosed within ````double
775+
backticks````.
768776

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

0 commit comments

Comments
 (0)