Doc improvements

[OriolAbril]

Description

This PR adds several new features to docs. Some of them are a not very well documented so I'll try to add this to the developer guide so we can make the most of these improvements.

Using see also

The see also section can also be used and links are generated automatically by sphinx. See compare for one example. We have to modify the css file to change the color, otherwise it is hardly readable. Any help would be greatly appreciated.

Referencing methods in other libraries

For now, xarray and pymc3 are configured to make it easy to reference their docs. This is possible thanks to intersphinx. Therefore, rst code such as:

:func:`pymc3:pymc3.sampling.sample`
:meth:`xarray.Dataset.sel <xarray:xarray.Dataset.sel>`  # example of modifying link text

Will directly link to the corresponding docs, see from_pymc3 and InferenceData.sel. The initial part is quite tricky, depending on what is referenced it has to be one or another key. The accepted keys can be found here, however in some cases it can be hard to guess. In such cases, the sphobjinv package can come in handy. It can search the documentation for us and return the interesting objects to tag:

$ sphobjinv suggest -t 90 -u https://docs.pymc.io/objects.inv "sampling.sample"
 
Remote inventory found.
 
:py:function:`pymc3.sampling.sample`
:py:function:`pymc3.sampling.sample_posterior_predictive`
:py:function:`pymc3.sampling.sample_posterior_predictive_w`
:py:function:`pymc3.sampling.sample_ppc`
:py:function:`pymc3.sampling.sample_ppc_w`
:py:function:`pymc3.sampling.sample_prior_predictive`
:std:label:`/api/inference.rst#pymc3.sampling.sample`
:std:label:`/api/inference.rst#pymc3.sampling.sample_posterior_predictive`
:std:label:`/api/inference.rst#pymc3.sampling.sample_posterior_predictive_w`
:std:label:`/api/inference.rst#pymc3.sampling.sample_ppc`
:std:label:`/api/inference.rst#pymc3.sampling.sample_ppc_w`
:std:label:`/api/inference.rst#pymc3.sampling.sample_prior_predictive`

The codes still have to be updated from :py:function: to :py:func: to follow match the accepted keys, see link above.

Referencing ArviZ functions

Same thing as above can be used: :py:func: and similar keywords.

Other

Several formatting fixes to reduce warnings and make sure all plots in docstring are correctly generated and updating from m2r to recommonmark to convert markdown to rst. Now everything should be sphinx3 compatible. Everything is now sphinx3 compatible.

Checklist

• Follows official PR format
• New features documented in the developer guide
• Code style correct (follows pylint and black guidelines)
• Changes are listed in changelog

[codecov]

Codecov Report

Merging #1184 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1184   +/-   ##
=======================================
  Coverage   93.12%   93.12%           
=======================================
  Files          94       94           
  Lines        9351     9351           
=======================================
  Hits         8708     8708           
  Misses        643      643           

Impacted Files	Coverage Δ
arviz/data/inference_data.py	81.88% <ø> (ø)
arviz/data/io_cmdstan.py	94.84% <ø> (ø)
arviz/data/io_cmdstanpy.py	100.00% <ø> (ø)
arviz/data/io_dict.py	89.89% <ø> (ø)
arviz/data/io_numpyro.py	95.23% <ø> (ø)
arviz/data/io_pymc3.py	92.74% <ø> (ø)
arviz/data/io_pyro.py	95.86% <ø> (ø)
arviz/data/io_pystan.py	98.67% <ø> (ø)
arviz/plots/kdeplot.py	100.00% <ø> (ø)
arviz/plots/rankplot.py	91.89% <ø> (ø)
... and 4 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0c89fc3...da978db. Read the comment docs.

[AlexAndorra]

This looks really great, thanks @OriolAbril !
I'd be curious to work on it with you if you need help -- not before next week though.

Disclaimer: I'm close to a noob on doc generation, but this seems like a good time to understand how this works on ArviZ -- plus, I'd like to do something similar on PyMC3, where the stats docs would directly redirect to ArviZ to avoid inconsistencies.

[OriolAbril]

Great! Thanks for the help! I can try to help with PyMC3 docs too.

Do you want to change anything else in the configuration? Otherwise we can merge and divide adding the references into several PRs

[AlexAndorra]

TBH I don't really now what's the best option yet 😅 Maybe the most efficient would be to have a video call and talk about it? Le ven. 15 mai 2020 à 21:55, Oriol Abril <[email protected]> a écrit :

…

Great! Thanks for the help! I can try to help with PyMC3 docs too. Do you want to change anything else in the configuration? Otherwise we can merge and divide adding the references into several PRs — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1184 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHIJMTHGLO2QU7I62YFQSZTRRWM4BANCNFSM4NAP5O6A> .

[canyon289]

I vote merging.

[canyon289]

Alright its been a day. Merging this. We can figure out cross docs later! Thanks @OriolAbril