I personally find this really difficult to comprehend. Perhaps, it might be better to simplify this description as much as possible and encourage users to provide their own markers to improve reproducibility?
Otherwise, the PR looks great!

Thanks for reviewing, @soupault! How about changing the above into:

None (no markers provided), the (default) markers are determined as the local
minima of the image. Note that the computation of the latter may follow
various assumptions (conventions); users are thus encouraged to pass markers
explicitly. For information, the computation of the default markers is
equivalent to applying :func:`skimage.morphology.local_minima` onto ``image``,
followed by :func:`skimage.morphology.label` onto the result, with
``connectivity=2``.

?

That reads better! I think there is a possibility to go even further:

None, the (default) markers are determined as the local minima
 of ``image``. Specifically, the computation is equivalent
 to applying :func:`skimage.morphology.local_minima` onto 
``image``, followed by :func:`skimage.morphology.label` (with 
``connectivity=2``) onto the result. Generally, users are 
encouraged to pass markers explicitly. 

Please, let me know what you think.

@soupault I think it reads well, thanks. Now, I'm wondering:

• I forget whether we want to encourage using skimage.morphology.label or skimage.measure.label (or maybe there's no preference?);
• I guess connectivity=2 should be replaced with connectivity=image.ndim?

skimage.morphology.label or skimage.measure.label

They refer to the same function in code, which is under skimage.measure., so I would point to that.

I guess connectivity=2 should be replaced with connectivity=image.ndim?

I have checked the code in details - the correct way seems to be to just say that the functions are called with the specified connectivity.

In the original issue, the local minima are calculated via locMin = label(local_minima(im)), with both functions using default connectivity=im.ndim, thus the confusion.

Thanks for checking, @soupault! 🙏

They refer to the same function in code, which is under skimage.measure., so I would point to that.

👍 👌

I have checked the code in details - the correct way seems to be to just say that the functions are called with the specified connectivity [...] default connectivity=im.ndim, thus the confusion.

Oh, right, right.

I actually thing it should be

as this references the parameter. At least that is what numpydoc recommends and uses.

Otherwise, I approve. :)

I see: "Enclose variables in single backticks." I was convinced of the opposite, because single backticks render just italic, whereas double backticks render like this:

Then I must update this elsewhere as well; and our documentation is full of variables enclosed in double backticks... 😬

Using single backticks in rST corresponds to emphasis rather than italics. Italics just happens to be what it is formatted as. At least that is how I explain that convention to myself.

and our documentation is full of variables enclosed in double backticks... 😬

As with many other inconsistencies. 😅

emphasis rather than italics. Italics just happens to be what it is formatted as.

Yes, yes, I know. I wrote the comment quickly and I actually thought to myself "I should be semantic and write 'emphasis' but, oh, well" 😅 But I find this consideration unrelated:

At least that is how I explain that convention to myself.

What does it explain? It's not intuitive to me at all that variables would be, by (any) convention, represented with emphasis style. To me, that 'steals' the emphasis use away from its original/natural/intuitive purpose: I would emphasize a word in a (plain English) sentence, in a docstring just like I would in any text. Now, if emphasis is used (by convention) to mean 'variable...' what can I use to emphasize a word or a group of words in a sentence? Conversely, I find that the label-like rendering of the double backticks is quite suitable/intuitive to mean 'this is a variable, not just any word in the sentence.'

As with many other inconsistencies. 😅

For sure...