pymc-labs / CausalPy

A Python package for causal inference in quasi-experimental settings
https://causalpy.readthedocs.io
Apache License 2.0
914 stars 65 forks source link

Improve docs through increased use of intersphinx #236

Open drbenvincent opened 1 year ago

drbenvincent commented 1 year ago
  1. Add more intersphinx mappings in conf.py:
    "pandas": ("https://pandas.pydata.org/docs/", None),
    "scikit-learn": ("https://scikit-learn.org/stable/", None),

    And also arviz when referring to idata for example.

  2. Use external intersphinx references when referring to external classes/functions. E.g. https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#role-external
OriolAbril commented 5 months ago

Extra note in case it is helpful. It isn't really necessary to use the :external: role, it is possible to use the cross-reference roles directly, by prepending a intersphinx_key: to the target, but that is only necessary in case there is a potential confusion. Also, these same roles can be used from markdown/jupyter files, not only rst. The only difference between rst and myst (md/ipynb file) is rst uses colons like :class:, myst uses curly brackets instead like {class}.

An example might clarify things. Once we add pymc to the intersphinx mapping for example, it will be possible to use :class:`pymc.Normal` to link to the rendered docstring for pymc.Normal; there is no object with which this could be confused, so no need to add an extra pymc: before it to indicate the external reference it should be retrieved from. We might also want to link to the glossary term tensor-like, which might (potentially) also exist on pytensor, jax or other docs that might also be added to intersphinx; consequently, its cross-reference should be :term:`pymc:tensor_like`. The target is tensor_like but we want to make sure this target is considered within the pymc documentation only.