Progressively update docs references

[OriolAbril]

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 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 links to scipy, matplotlib and bokeh functions from this source).

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 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.
• hdi (maybe a reference would further improve the docstring)
• 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
  • ...

[fairka]

Hey can I have this project?

[OriolAbril]

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?

[OriolAbril]

@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.

[HayesJohnD]

I this is not assigned to anyone, if not I would like to work on this.

[OriolAbril]

@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.

[HayesJohnD]

Ok, I will start on the InferenceData.sel/InferenceData.isel part.

[OriolAbril]

Great! Feel free to ask any question here or on gitter

[Srijha09]

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

[OriolAbril]

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

[Srijha09]

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

[OriolAbril]

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

[Srijha09]

Okay thanks. I'll do that.

[Srijha09]

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?

[OriolAbril]

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.

[Srijha09]

Alright thanks.

[Srijha09]

Hi just to clarify, since this issue has been closed shall I update the other functions as well by doing some PRs?
Let me know

[OriolAbril]

Yes, the issue is not fixed yet, only partially. It was closed automatically when merging due to using "resolve" right before the issue.

[Srijha09]

Oh okay.