DOC: Clarify recommendations regarding use of backticks #525

mdhaber · 2024-01-14T18:47:46Z

The Style guide currently gives the following recommendations about backticks:

In the Parameters section:

Enclose variables in single backticks

For inline display use double backticks

Variable, module, function, and class names should be written between single back-ticks (numpy).

Contributors (and even maintainers) frequently interpret and/or apply these recommendations inconsistently. This PR attempts to clarify the recommendations to avoid multiple interpretations.

Related issues:

Change single backticks in Sphinx to render as code sympy/sympy#13519

Follow-up work includes:

doc/format.rst

mdhaber · 2024-01-14T18:50:09Z

doc/format.rst

+
+- Module, function, and class names should be enclosed within ```single
+  backticks```. These are intended to render as hyperlinks (e.g. `numpy`). If
+  the hyperlinks do not render as intended, [insert reference to documentation


Where should users be referred?

Suggestions on that to include here?

To me, the important distinction to make is: double-backticks is for monospace/code literals, single backticks are for references. If you want to attempt to link to something, use single backticks. If you just want monospace formatting without an attempted link, use double-backticks (the exception of course being numpydoc parameters).

mdhaber · 2024-01-14T18:52:17Z

doc/format.rst

+  ``monospaced`` hyperlink to the relevant definition in a future version of
+  numpydoc.


Perhaps this should be removed, but I wanted to mention it because it is the only reason I can see for using single backticks instead of double backticks. Otherwise, use of single backticks only causes problems with name collisions and renders in italics (which usually means "emphasis") where monospace (which means code) would be more clear.

I'd just remove this - it's probably more detail than most users are interested in (and is not necessarily correct - the actual rendering of e.g. italics is actually dictated by the sphinx theme).

stefanv

Thanks @mdhaber! This looks good overall; I just have a few naive questions.

stefanv · 2024-01-14T21:07:22Z

doc/format.rst

-Enclose variables in single backticks.  The colon must be preceded
-by a space, or omitted if the type is absent.
+The colon must be preceded by a space, or omitted if the type is absent.
+When referring to a parameter in the description field or elsewhere within


Perhaps this would be simpler as "referring to any parameter of the function being documented", or something along that vein?

So basically remove "in the description field or...". That's probably fine. I think I wanted to point out specifically that this advice was not limited to references within the parameter documentation, but maybe it's better overall to just keep it simple.

I'd vote for simple as well, something like:

When referring to a parameter elsewhere in the docstring, enclose its name in single backticks.

Where else can the variable live? Returns? Class docs, etc.?

I'm not sure I understand. Is the question about what constitutes a "parameter", where else a parameter might be mentioned, or something else?

Another intent of the wording here was to try to clarify that parameters of other functions referred to in the current docstring are not subject to this rule. But I think @rossbar's wording does that implicitly, so I've changed it locally and will push shortly.

doc/format.rst

stefanv · 2024-01-14T21:10:49Z

doc/format.rst

@@ -717,7 +726,9 @@ Other points to keep in mind
  (i.e. scalar types, sequence types), those arguments can be documented
  with type `array_like`.

-* Links : If you need to include hyperlinks in your docstring, note that
+* Links : Sphinx will automatically create hyperlinks to module, function,


Is this recommended practice? I think most libraries use :pyfunc: etc. Genuinely asking, I don't know.

It's what is done in SciPy, I think. I think Sphinx only needs more information if there is a name collision.

Again, I think this reaches beyond what numpydoc would recommend (see above). The original information here about name collisions is relevant

Is this recommended practice?

I think it's a tradeoff. With the standard configuration default_role = "py:obj:", using single backticks is equivalent to writing `:py:obj:`target`, which will attempt to link against most things (func, ref, meth, attr, etc.). The primary motivation for excluding the explicit roles is docstring readability in the terminal. However there's nothing to say that you can't or shouldn't use the explicit roles - that's perfectly valid and is up to the library to decide.

It's fine with me to add something about this being a project specific thing and mention the more explicit options, but if it is very common for projects to use single backticks, I think something should be mentioned. What can we say without over-stepping numpydoc's role?

Let's add the common footnote about default role.

mdhaber · 2024-01-14T21:35:04Z

doc/format.rst

-* Links : If you need to include hyperlinks in your docstring, note that
+* Links : Sphinx will automatically create hyperlinks to module, function,
+  and class documentation if a recognized name is included within single
+  backticks (e.g. `numpy`). If you need to include other hyperlinks, note that


Suggested change

backticks (e.g. `numpy`). If you need to include other hyperlinks, note that

backticks (e.g. ```numpy``` renders as `numpy`). If you need to include other hyperlinks, note that

But it is not rendering correctly right now.

rossbar

Thanks for bringing this up @mdhaber ! There's a lot of nice improvements here, though I think a lot of the recommendations on what to enclose in single backticks are beyond numpydoc's purview and shouldn't necessarily be recommended here.

The linking via single backticks is handled by sphinx proper, not numpydoc, and depends on the configuration and thoroughness of auto-generated stubs for each individual project.

I tend to think of the markup as:

double-backticks == monospace formatting with no linking
single-backticks == attempted linking

The thing that breaks the above is numpydoc's parameter recommendation, which is what I'd like to fix in #484

rossbar · 2024-01-17T07:20:04Z

doc/format.rst

-Enclose variables in single backticks.  The colon must be preceded
-by a space, or omitted if the type is absent.
+The colon must be preceded by a space, or omitted if the type is absent.
+When referring to a parameter in the description field or elsewhere within


I'd vote for simple as well, something like:

When referring to a parameter elsewhere in the docstring, enclose its name in single backticks.

doc/format.rst

rossbar · 2024-01-17T07:38:38Z

doc/format.rst


+When referring to an attribute in the description field or elsewhere within


The recommendations for methods/attributes are tricky - this is actually not something that numpydoc handles directly. The :meth: and :attr: are roles are built-in to sphinx itself. The fact that putting method and attribute names in single backticks references the relevant doc is a consequence of the sphinx default_role (which I believe is :py:obj: if not explicitly configured), which handles cross-references without any specific type information.

However, there are many cases where this would not be recommended - i.e. if a project uses something other than :py:obj: as the default role, then the cross-referencing may not work as expected leading broken links and nitpick warnings from sphinx. More likely, if a method or attribute does not have its own doc stub (i.e. it's excluded from the relevant autosummary directive), then this will also result in broken links.

In other words, I don't think this is a recommendation that numpydoc should be making. While it is generally good advice (for a standard sphinx configuration) it's not strictly handled by numpydoc thus not really part of the docstring standard, rather more general sphinx/rst advice. My vote would be to exclude these two recommendations, or link to relevant external sphinx docs to explain when wrapping Python objects in single backticks makes sense.

I see. I would prefer not to remove these entirely.

Is it within numpydoc's purview to recommend that these be rendered as links?

If so, do I understand correctly that typical options will be 1) just single backticks, 2) single backticks preceded by :attr:, or 3) single backticks preceded by some other role, and that the choice is up to the project?

The single-backquote-around-a-parameter concept is part of the original numpydoc specification, though, so I'm not sure we can steer clear of it.

Not sure what to say about projects that reconfigure the default role. Technically, their docstrings are no longer numpydoc compliant, but it's not a big deal as long as they consistently use whichever roles they do.

Thanks @stefanv for bringing this up again.

@rossbar can you suggest a compromise here? I think we need to address methods and attributes in some capacity. What can we say about them?

The single-backquote-around-a-parameter concept is part of the original numpydoc specification, though, so I'm not sure we can steer clear of it.

Yes, but this is only for the function parameters - recommending that class attributes and methods also be wrapped in single backticks relates to sphinx, not numpydoc, and is nowhere currently mentioned in the numpydoc standard. Generally speaking it's a fine thing to recommend, and if this were a sphinx tutorial I would be +1 for adding it - I'm only leery because this document "defines" the numpydoc docstring standard, and as written this would likely introduce more broken links in documentation (nor does it relate to the "function parameters should be in single backticks" recommendation that has been around since the beginning).

Not sure what to say about projects that reconfigure the default role. Technically, their docstrings are no longer numpydoc compliant

That's not strictly true - the numpydoc standard doesn't prescribe how projects configure the default_role and there are certainly cases where projects may want to override it. To make matters even more confusing, the default_role configuration value can be overridden with the .. default-role:: directive on a per-file basis. The only place where there's currently a collision is the long-standing "function parameters should be in single backticks" recommendation. Currently, numpydoc recommends this but does not implement anything specific for it, so the rendered docs end up using the default_role. The real solution here is to fix this in numpydoc - see #484.

can you suggest a compromise here? I think we need to address methods and attributes in some capacity. What can we say about them?

Since this is generally good advice, I'd be perfectly happy to put it in with softer wording; i.e. something that is very clearly a suggestion and not a necessary part of docstring formatting. Perhaps a less wordy version of:

When combined with `sphinx.ext.autodoc` or `sphinx.ext.autosummary`, included {attributes/methods} become valid link targets and can be referenced elsewhere in the docstring with single backticks. See <link to autoclass> for details.

This is hopefully clear, concise, and should do the job for ~95% of use-cases in practice. I'd personally be inclined to include a footnote after "single backticks" to add an additional note about the default role, e.g.

docstring with single backticks[^1]. See <link to autoclass> for details. [^1]: Depending on the configuration of the `default_role <link to default role>`_ for your project.

but it's not necessary.

👍 My expectation is only for backticks, anywhere in the docstring, to link to parameter names. It looks like we are in agreement on that, and I'm fine with whatever else is added as Sphinx guidance.

"function parameters should be in single backticks"

Is that documented, though? I see "Enclose variables in single backticks" (emphasis mine). That is in the Parameters section, but I thought that if "variables" were limited to "function parameters" it would say so. The ambiguity there is what led me to try to clarify.

See <link to autoclass> for details.

Is this what you have in mind?
https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoclass

Depending on the configuration of the ``default_role <link to default role>``_ for your project.

This?
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-default_role

Why does numpydoc make a recommendation about single backticks around parameters if it doesn't do anything with them? Has the intent always been that eventually they would link as you do in gh-484; it just hasn't happened yet?

My best guess is that the intent was to state "function parameters", but 2008 is a long time ago.

Why does numpydoc make a recommendation about single backticks around parameters if it doesn't do anything with them?

Yeah this is likely an accident of fate - single backticks has always changed the formatting in the rendered docs (even if it was only to the formatting of broken rst links)

doc/format.rst

rossbar · 2024-01-17T07:52:04Z

doc/format.rst

@@ -717,7 +726,9 @@ Other points to keep in mind
  (i.e. scalar types, sequence types), those arguments can be documented
  with type `array_like`.

-* Links : If you need to include hyperlinks in your docstring, note that
+* Links : Sphinx will automatically create hyperlinks to module, function,


Again, I think this reaches beyond what numpydoc would recommend (see above). The original information here about name collisions is relevant

Is this recommended practice?

I think it's a tradeoff. With the standard configuration default_role = "py:obj:", using single backticks is equivalent to writing `:py:obj:`target`, which will attempt to link against most things (func, ref, meth, attr, etc.). The primary motivation for excluding the explicit roles is docstring readability in the terminal. However there's nothing to say that you can't or shouldn't use the explicit roles - that's perfectly valid and is up to the library to decide.

Co-authored-by: Ross Barnowski <rossbar@berkeley.edu> Co-authored-by: Matt Haberland <mhaberla@calpoly.edu>

mdhaber

Thanks all. @rossbar can you make suggestions on what we can write in these tricky spots? I'd rather not remove them altogether. The hope here was to make numpydoc's recommendations about backticks usage something that can be read and followed. If numpydoc doesn't have a requirement about something, maybe that's fine, but can we say that explicitly? Given all the misuse and confusion (I can produce dozens of PRs if need be), I think it's worth saying something.

mdhaber · 2024-02-07T06:24:26Z

doc/format.rst

-Enclose variables in single backticks.  The colon must be preceded
-by a space, or omitted if the type is absent.
+The colon must be preceded by a space, or omitted if the type is absent.
+When referring to a parameter in the description field or elsewhere within


I'm not sure I understand. Is the question about what constitutes a "parameter", where else a parameter might be mentioned, or something else?

mdhaber · 2024-02-07T06:28:05Z

doc/format.rst


+When referring to an attribute in the description field or elsewhere within


Thanks @stefanv for bringing this up again.

@rossbar can you suggest a compromise here? I think we need to address methods and attributes in some capacity. What can we say about them?

mdhaber · 2024-02-07T06:36:28Z

doc/format.rst

@@ -717,7 +726,9 @@ Other points to keep in mind
  (i.e. scalar types, sequence types), those arguments can be documented
  with type `array_like`.

-* Links : If you need to include hyperlinks in your docstring, note that
+* Links : Sphinx will automatically create hyperlinks to module, function,


It's fine with me to add something about this being a project specific thing and mention the more explicit options, but if it is very common for projects to use single backticks, I think something should be mentioned. What can we say without over-stepping numpydoc's role?

mdhaber · 2024-02-07T06:36:48Z

doc/format.rst

+
+- Module, function, and class names should be enclosed within ```single
+  backticks```. These are intended to render as hyperlinks (e.g. `numpy`). If
+  the hyperlinks do not render as intended, [insert reference to documentation


Suggestions on that to include here?

rossbar

FWIW I found this summary from @jnothman over in a related scikit-learn issue very relevant: scikit-learn/scikit-learn#11186 (comment)

timhoffm · 2024-05-14T23:12:50Z

IMHO, the recommendation for single backticks should be complemented with an explanation. Something like

Single backticks are historically used as a means of highlighting. Sphinx tries to resolve them with the default_role, which in the default configuration results in italics. If you use a different default_role in Sphinx you may need to resort to different ways of highlighting, e.g. double backticks or *param* to prevent unintended links or link errors.

doc/format.rst

rossbar

Awesome, thanks for all the hard work here @mdhaber . I think the current wording recommendations are spot on. We can follow-up with more detailed "troubleshooting" docs to handle the cases when single-backtick behave differently than what users expect.

mdhaber · 2024-06-10T21:43:04Z

@rossbar @Carreau @stefanv something not covered by this PR or pydata/pydata-sphinx-theme#1852 is whether short literals like True and 0 should appear in monospaced font when they refer to code (e.g. "None" refers to code when capitalized within a sentence). For the sake of consistency, I'd like for the style guide to recommend that they be rendered as code (and that means double backticks) both in normal text and in parameter/attribute type descriptions. For example:

axis : ``int``, ``tuple``, or ``None``
   blah blah

Of course, "axis" would appear as axis automatically if the suggestion in pydata/pydata-sphinx-theme#1852 is approved. We probably need control within the descriptions, though. (Unless the theme or something else can make an inference?)

Thoughts?

stefanv · 2024-06-10T22:07:27Z

That is probably more consistent, but would require rewriting nearly all docstrings.
/cc @lagru who is working on docstub

mdhaber · 2024-06-10T23:02:50Z

Many docstrings don't comply with the recommendations already made in this PR. We decided it's OK because compliance with this style guide is optional and can be improved gradually, right? The intent is to reduce future inconsistency that creeps in when the guideline isn't specified.

lagru · 2024-06-11T03:28:42Z

As far as I understand this, this should have no impact on docstub.

Carreau · 2024-06-11T09:51:28Z

I don't see any reason why None, True and other constant would not be single backticks as they should be crossrefed by intersphinx (https://docs.python.org/3/library/constants.html#True).

Imho the discussion of wether it should use single or double backticks should only be a semantic one, not a visual style one.

In all case I think we can ask:

Can it be replaced by a directive without changes to the content of the backtick?
- Yes -> Single
- No -> Double.

For example `True` -> :py:obj:`True`, yep single. `from numpy import sin` -> :?:??:`from numpy import sin` I don't see what we can use -> double.

mdhaber · 2024-06-11T12:43:52Z

Ah, single is even better then. I didn't consider that they would link.

Carreau · 2024-06-11T12:58:40Z

From a quick test:

Which match my expectation, I guess `0` could link, but as it's a specific value, I see why it does not.

Add the special case for constant, and try to separate semantic (can link), to style (monospace, link) See also numpy#525

Carreau · 2024-06-11T13:21:27Z

see #565 for my take on this.

doc/format.rst

13d4678

mdhaber commented Jan 14, 2024

View reviewed changes

mdhaber requested a review from rossbar January 14, 2024 18:52

mdhaber changed the title ~~Clarify use of backticks~~ DOC: Clarify recommendations regarding use of backticks Jan 14, 2024

stefanv reviewed Jan 14, 2024

View reviewed changes

mdhaber commented Jan 14, 2024

View reviewed changes

rossbar reviewed Jan 17, 2024

View reviewed changes

jarrodmillman added the type: Documentation label Feb 5, 2024

Apply suggestions from code review

4895a4b

Co-authored-by: Ross Barnowski <rossbar@berkeley.edu> Co-authored-by: Matt Haberland <mhaberla@calpoly.edu>

mdhaber mentioned this pull request Feb 5, 2024

ENH: stats.wilcoxon: rewrite for speed and clarity; add PermutationMethod support scipy/scipy#19770

Merged

mdhaber commented Feb 7, 2024

View reviewed changes

mdhaber mentioned this pull request Feb 13, 2024

ENH: Add vectorized scalar minimization bracket finder scipy/scipy#19757

Merged

larsoner mentioned this pull request Mar 6, 2024

Require sphinx 6 #530

Merged

rossbar reviewed Mar 7, 2024

View reviewed changes

yarnabrina mentioned this pull request Mar 13, 2024

[MNT] create build tool to check invalid backticks sktime/sktime#6088

Merged

2 tasks

mdhaber mentioned this pull request Apr 4, 2024

ENH: stats: add random variable infrastructure mdhaber/scipy#110

Closed

mdhaber added 2 commits June 3, 2024 07:45

MAINT: partially respond to some comments to prepare for discussion

f4bb0f2

Merge remote-tracking branch 'origin/backticks' into backticks

61c50b5

mdhaber mentioned this pull request Jun 3, 2024

Recommendations regarding use of backticks in documentation scientific-python/summit-2024#22

Closed

Carreau reviewed Jun 3, 2024

View reviewed changes

doc/format.rst Show resolved Hide resolved

Carreau reviewed Jun 3, 2024

View reviewed changes

doc/format.rst Show resolved Hide resolved

Merge remote-tracking branch 'upstream/main' into backticks

b39163a

mdhaber commented Jun 3, 2024

View reviewed changes

doc/format.rst Show resolved Hide resolved

mdhaber commented Jun 3, 2024

View reviewed changes

doc/format.rst Outdated Show resolved Hide resolved

MAINT: adjustments per review

9792831

mdhaber requested a review from rossbar June 3, 2024 18:00

MAINT: fix links to numpy

4b3afe9

Carreau mentioned this pull request Jun 3, 2024

Use intersphinx registry to avoid out of date links. #563

Merged

rossbar approved these changes Jun 3, 2024

View reviewed changes

rossbar merged commit b7c6688 into numpy:main Jun 3, 2024
23 checks passed

stefanv added this to the 1.8.0 milestone Jun 3, 2024

This was referenced Jun 3, 2024

Consistent use of monospaced font pydata/pydata-sphinx-theme#1852

Open

ENH: stats._xp_mean, an array API compatible mean with weights and nan_policy scipy/scipy#20743

Merged

Carreau added a commit to Carreau/numpydoc that referenced this pull request Jun 11, 2024

DOC: Extend explanation on single vs double backticks.

ed89d7f

Add the special case for constant, and try to separate semantic (can link), to style (monospace, link) See also numpy#525

Carreau mentioned this pull request Jun 11, 2024

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

Open

		``monospaced`` hyperlink to the relevant definition in a future version of
		numpydoc.

	backticks (e.g. `numpy`). If you need to include other hyperlinks, note that
	backticks (e.g. ```numpy``` renders as `numpy`). If you need to include other hyperlinks, note that


		When referring to an attribute in the description field or elsewhere within

DOC: Clarify recommendations regarding use of backticks #525

DOC: Clarify recommendations regarding use of backticks #525

Conversation

mdhaber commented Jan 14, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stefanv left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdhaber Jan 14, 2024 • edited Loading

Choose a reason for hiding this comment

rossbar left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdhaber Jan 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdhaber Feb 14, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdhaber left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rossbar left a comment

Choose a reason for hiding this comment

timhoffm commented May 14, 2024 • edited Loading

rossbar left a comment

Choose a reason for hiding this comment

mdhaber commented Jun 10, 2024 • edited Loading

stefanv commented Jun 10, 2024

mdhaber commented Jun 10, 2024 • edited Loading

lagru commented Jun 11, 2024

Carreau commented Jun 11, 2024 • edited Loading

mdhaber commented Jun 11, 2024

Carreau commented Jun 11, 2024

Carreau commented Jun 11, 2024

mdhaber commented Jan 14, 2024 •

edited

Loading

mdhaber Jan 14, 2024 •

edited

Loading

mdhaber Jan 20, 2024 •

edited

Loading

mdhaber Feb 14, 2024 •

edited

Loading

mdhaber left a comment •

edited

Loading

timhoffm commented May 14, 2024 •

edited

Loading

mdhaber commented Jun 10, 2024 •

edited

Loading

mdhaber commented Jun 10, 2024 •

edited

Loading

Carreau commented Jun 11, 2024 •

edited

Loading