Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve docs through increased use of intersphinx #236

Open
drbenvincent opened this issue Sep 11, 2023 · 1 comment
Open

Improve docs through increased use of intersphinx #236

drbenvincent opened this issue Sep 11, 2023 · 1 comment
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers

Comments

@drbenvincent
Copy link
Collaborator

  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
@drbenvincent drbenvincent added documentation Improvements or additions to documentation good first issue Good for newcomers labels Sep 11, 2023
@OriolAbril
Copy link
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers
Projects
None yet
Development

No branches or pull requests

2 participants