Historically, do we have a policy on where to place references? We already reference Schölkopf in the user guide.

I do like having a link to the reference while reading the docstring, maybe we can link the docstring to the reference in the user guide?

CC @NicolasHug

My main position is that references without backlinks are almost entirely useless and even counterproductive/confusing when there's more than one. Without a backlink, we don't know what the reference references to.

I see all the refs here have backlinks, which is great. I don't mind having them in the docstrings as long as they're properly maintained.

However it does raise the issue of duplicated references and duplicated descriptions between the docstrings and the UG. I feel like this is something we'd want to avoid. My preference here is to only have the ref section in the UG, and have more detailed parameter descriptions there as well. Then we can link to the UG from the docstrings when relevant / needed.

My preference here is to only have the ref section in the UG, and have more detailed parameter descriptions there as well. Then we can link to the UG from the docstrings when relevant / needed.

I agree with the previous comment apart of this one mainly because, sometimes, I don't want to go in the user guide to get the info. I would expect to get the paper of the algorithm at minima. Here, this is the typical case that it is tricky because the paper does not provide the implementation of inverse_transform so I would also like to know about it :)

For the solver, I might agree that refering to the user guide could be enough because the default exact algorithm is in the main paper.

I think it's useful to have it in the code/docstring, especially when it makes it possible to give more details on the behavior of the parameters by cross-linking from the parameters section when appropriate as done here.

Why is it a problem to have it both in the code/docstring and the user guide?

Why is it a problem to have it both in the code/docstring and the user guide?

Duplicated content get out of sync, which is even more harmful to docs than to code. Inevitably, after a while, A says X and B says Y, and readers don't know which one they should trust. Also, twice as much work for us to maintain the same thing in 2 places. We'll forget.

The only way I found to not duplicate content is to write most info in the user guide, and link from the docstring to the user guide.

especially when it makes it possible to give more details on the behavior of the parameters by cross-linking from the parameters section when appropriate as done here

I'm not sure what you mean, but we can cross-link from docstrings to UG too.

Personally, I feel like the only good thing about refs in the docstring is that in theory you can get to the papers from within the code / IDE. But this alone doesn't outweigh the risks, IMHO. And everybody can look at the docs online on a browser. With Latex and links everywhere, our docs are becoming more and more "html only" anyway (and it's for the best, if you ask me).

As an example of my "strategy" of linking from the docstrings to the UG, and keeping the references in the UG:

categorical_features and monotonic_constraints docstrings of
https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.HistGradientBoostingClassifier.html