Repository: arviz-devs/arviz

Issue:
Progressively update docs references
Add links to related functions in docstrings (applies to both links to internal and external functions), also add See also sections where relevant. Follow up of #1184. Places where references are of particular importance are: `kwargs` description to ease consulting of the documentation relevant to the kwargs so users know what keys are supported; and functions that take as input the output of a previous one

For details on how to do so, read the [hyperlinks section](https://arviz-devs.github.io/arviz/contributing/developer_guide.html#hyperlinks) in the developer guide. Moreover, the docstring of `hdi` and `plot_hdi` are good examples.

## External references
An example of external reference can be found at `plot_hdi` page (see how [rendered page](https://arviz-devs.github.io/arviz/api/generated/arviz.plot_hdi.html) links to scipy, matplotlib and bokeh functions from [this source](https://github.com/arviz-devs/arviz/blob/main/arviz/plots/hdiplot.py#L35-L78)).

## Internal references
The same `plot_hdi` also has an internal reference to `hdi`. The links are the same as in the previous section. 

## See also section
An example of See also section can be found at [`compare`](https://arviz-devs.github.io/arviz/api/generated/arviz.compare.html) page

## Status
This should help tracking what has been done. We could open an issue for every single function but that would probably get out of hand fast and make keeping track harder. Functions where work is halfway will be listed below without checkmark, updated functions will be checked and all missing functions are free and unassigned. 

If you are interested in working on this, check the list to see what functions are available and comment which (1-4 functions per PR seem like a reasonable number, don't try to work on too many at the same time) would you like to tackle. 

* [ ] plot_hdi: nearly finished, only external references for `backend_kwargs` are missing.
* [x] hdi (maybe a reference would further improve the docstring)
* [x] InferenceData.sel/InferenceData.isel: should have all references to xr.Dataset.sel/isel with hyperlink and also a see also section linking them to each other and to the respective xarray versions
* [ ] Other InferenceData methods: intersphinx is present and linking to relevant places, a see also section would be appreciated. This one is **not** begginer friendly as it should be added programatically by `_extend_...` cc @percygautam 
* [ ] compare: extend see also section, maybe use references too? plot_separation is a good example on how to format references in docstrings
* all other functions...
   * [ ] plot_xyz
   * [ ] stats xyz
   * [ ] diagnostics xyz
   * [ ] ...


Discussion:
Hey can I have this project?
Yes, thanks! 

There are many functions to update, so it is probably better to divide the issue into several pull requests. Does this sound good? What functions were you planning to update first?
@JeevaJyothiSundaram I have just noticed you downvoted the previous comment, were you planning on working on this issue? There are plenty of functions to update.
I this is not assigned to anyone, if not I would like to work on this.
@just-linux you can work on this, thanks! 

Comment here the functions you are planning to work on so work is not duplicated and that's about it, once updated I'll take care of updating the checklist in the issue description.
Ok, I will start on the ***_InferenceData.sel/InferenceData.isel_*** part.
Great! Feel free to ask any question here or on gitter
Hi, I would like to work on this issue. Can I work on plot_hdi, compare and InferenceData.sel/InferenceData.isel(since its not completed) if its not taken by anyone? Let me know


Thanks
That would be great @Srijha09. Note I have updated the link in the description to https://arviz-devs.github.io/arviz/contributing/developer_guide.html#hyperlinks. Let us know if you have any doubts
Thanks for updating the link. Just a clarification before I do a PR, I am supposed to add external references on backend_kwargs to bokeh and matplotlib methods, right? 
Also, I went through the InferenceData.sel/InferenceData.isel, it looks like all the references and the see also section has been  added referencing to each other.
https://arviz-devs.github.io/arviz/api/generated/arviz.InferenceData.isel.html
https://arviz-devs.github.io/arviz/api/generated/arviz.InferenceData.sel.html


> I am supposed to add external references on backend_kwargs to bokeh and matplotlib methods, right?

Yes, you'll have to check the source code to see to which function/method they are passed and add a link there using intersphinx. 

> Also, I went through the InferenceData.sel/InferenceData.isel, it looks like all the references and the see also section has been added referencing to each other.
https://arviz-devs.github.io/arviz/api/generated/arviz.InferenceData.isel.html
https://arviz-devs.github.io/arviz/api/generated/arviz.InferenceData.sel.html

Thanks! I must have forgotten to update the description, I'll do it now
Okay thanks. I'll do that. 
Hey, also I see you have added other functions as well. Would it be better if I add all the references to the functions and create a single pull request?
>  I see you have added other functions as well. Would it be better if I add all the references to the functions and create a single pull request?

yes, I figure the last point about _all_ other functions in the library wasn't clear enough so I tried to be more explicit. I would suggest making several PRs modifying 1-3 files each, otherwise the single PR touching nearly all the library is doomed to have multiple git conflicts and need to be rebased a few times which in the long run will be more work than multiple PRs.
Alright thanks. 

Resolving patch:
diff --git a/arviz/plots/hdiplot.py b/arviz/plots/hdiplot.py
--- a/arviz/plots/hdiplot.py
+++ b/arviz/plots/hdiplot.py
@@ -71,7 +71,9 @@ def plot_hdi(
     backend : {"matplotlib","bokeh"}, optional
         Select plotting backend.
     backend_kwargs : bool, optional
-        These are kwargs specific to the backend being used. Passed to ::``
+        These are kwargs specific to the backend being used, passed to
+        :meth:`mpl:matplotlib.axes.Axes.plot` or
+        :meth:`bokeh:bokeh.plotting.figure.Figure.patch`.
     show : bool, optional
         Call backend show function.
 
diff --git a/arviz/stats/stats.py b/arviz/stats/stats.py
--- a/arviz/stats/stats.py
+++ b/arviz/stats/stats.py
@@ -156,6 +156,14 @@ def compare(
     --------
     loo : Compute the Pareto Smoothed importance sampling Leave One Out cross-validation.
     waic : Compute the widely applicable information criterion.
+    plot_compare : Summary plot for model comparison.
+
+    References
+    ----------
+    .. [1] Vehtari, A., Gelman, A. & Gabry, J. Practical Bayesian model evaluation using
+        leave-one-out cross-validation and WAIC. Stat Comput 27, 1413–1432 (2017)
+        see https://doi.org/10.1007/s11222-016-9696-4
+
     """
     names = list(dataset_dict.keys())
     if scale is not None:


Test patch: