I personally don't mind having to merge master and fix conflicts on my own PRs, and I don't think there are many PRs which can be merged w/o any changes from their current state anyway.

It's not only merge conflicts, it will also make git blame more confusing. 5k lines diff is around ~3-4% of the scikit-learn code base (including docs but excluding tests), scattered across different files. That's significant.

Also personally I would rather use a consistent docstring rst formatting across different projects.

+0.0 on this. Let's see what other dev think.

BTW, if this does get merged, we should run autopep8 on the code, as currently that only produces a ~500 lines diff, i.e. 10x less that this one, and we have been avoiding that for quite some time due to merge conflicts. Though that wouldn't fix all PEP8 issues either.

Note however that this PR only changes documentation, while autopep8 would affect other parts of the code as well. Conflicts are much easier to solve and merge mistakes are less harmful when they only concern documentation.

@amueller @thomasjpfan what do you think? This already has some conflicts. We should either do it (which I'd be in favor), or just close this and the issue.

I’m in favor.

And in many cases, for no benefit (i.e. there is no link) other than establishing best practices.

"Best practices" is a powerful incentive

I think it would be good to make a decision here to avoid @adrinjalali the trouble of continuously syncing master. I still vote +0 but it looks like there is sufficient support?

Should someone make the call (or at least approve the PR), or is there still unanswered comments?

A decision would be nice :P

There is also the concern it might generate too many links...?

And on top of that, it will generate links that should not be generated. We experienced that in #14357 with @thomasjpfan where plot would resolve to the sklearn method while it was in fact referring to matplotlib's plot.

With this PR merged, the default behaviour in contributions will now be to use single backticks, and that will sometimes resolve to things when it should not, creating confusion in the documentation. And we, as reviewers, won't see it unless we check the renderred doc and actually click on the links to make sure they make sense.

I still think we should not go against sphinx and use single backticks only when we're sure we want to resolve to something. Double backticks should be the default.

I won't vote -1 but I want to make sure we're all aware of these pitfalls.

so should we close this one and your issue @amueller ?

I still think we should not go against sphinx and use single backticks only when we're sure we want to resolve to something.

We still need to go into the rendered docs to be sure that it resolves anything.(Maybe the class has a plot method or the term was just added to the glossery).

Currently our docs are full of single and double backticks, where a good amount of single backticks mean "code block". We need to set a standard or else it will continue to be like this.

Personally, 95% of the time, when I use single backticks, I mean code block (because markdown).

I think this might not be worth it and I'm happy to close.
Thinking a bit more about it, it might make sense to do this for select things, like Pipeline and train_test_split or partial_fit maybe but I don't really care either way. And look at the conflicts this has already.

Currently our docs are full of single and double backticks, where a good amount of single backticks mean "code block". We need to set a standard or else it will continue to be like this.

That standard is the .rst standard. The correct way to fix this is to transform single backticks into double backticks, not the other way around.

Let's close it.