Add pre-commit check for docs cross-references

[symeneses]

It closes #5317 in #DataUmbrellaPyMCSprint

Adds a hook to check for docs.pymc.io inside docs/source/.

Depending on what your PR does, here are a few things you might want to address in the description:

• linting/style checks have been run

This PR should be merged after the existing links are reviewed. The hook is detecting these references to be fixed:

• docs/source/contributing/developer_guide.rst:65:https://docs.pymc.io/Probability\_Distributions.html#using-pymc-distributions-without-a-model).
• docs/source/contributing/developer_guide.rst:113:https://docs.pymc.io/Probability\_Distributions.html#custom-distributions
• docs/source/contributing/developer_guide.rst:377: transformation https://docs.pymc.io/notebooks/api_quickstart.html?highlight=chain%20transformation`__).
• docs/source/contributing/developer_guide.rst:693:method https://docs.pymc.io/notebooks/sampling_compound_step.html`__.
• docs/source/contributing/developer_guide.rst:696:RVs https://docs.pymc.io/notebooks/sampling_compound_step.html?highlight=compoundstep#Specify-compound-steps`__.
• docs/source/contributing/developer_guide.rst:714:doc https://docs.pymc.io/notebooks/sampling_compound_step.html#Specify-compound-steps`__.
• docs/source/contributing/developer_guide.rst:913: - Using “black box” likelihood function by creating a custom Aesara Op <https://docs.pymc.io/notebooks/blackbox_external_likelihood.html>__
• docs/source/contributing/developer_guide_implementing_distribution.md:26:Before creating a new RandomVariable make sure that it is not offered in the Numpy library.
• docs/source/contributing/release_checklist.md:25:+ Make sure the new version appears at the website and that docs.pymc.io/en/stable points to it.
• docs/source/glossary.md:14: Choosing which function or method implementation to use based on the type of the input variables (usually just the first variable). For some examples, see Python's documentation for the singledispatch decorator.
• docs/source/learn/examples.md:13:- https://docs.pymc.io/en/stable/Probability_Distributions.html
• docs/source/learn/examples.md:16:- https://docs.pymc.io/en/stable/PyMC3_and_Theano.html

[OriolAbril]

Thanks! Will review asap

[OriolAbril]

commenting with what I believe are the right sphinx cross references for these links, but we'll still need to check the preview to make sure they work.

docs/source/contributing/developer_guide.rst:10:`PyMC <https://docs.pymc.io/>`__ is a Python package for Bayesian

:doc:`PyMC <index>`

docs/source/contributing/developer_guide.rst:17:quickstart <https://docs.pymc.io/notebooks/api_quickstart.html>`__. A more accessible, user facing deep introduction can be found in

:ref:`quickstart <pymc_overview>`

docs/source/contributing/developer_guide.rst:24:the `documentation <https://docs.pymc.io/Probability_Distributions.html>`__. The source
docs/source/contributing/developer_guide.rst:66:https://docs.pymc.io/Probability\_Distributions.html#using-pymc-distributions-without-a-model).
docs/source/contributing/developer_guide.rst:115:https://docs.pymc.io/Probability\_Distributions.html#custom-distributions

No idea about this one, will have to check where it was linking originally, this page is now gone from the docs I think 🤔

docs/source/contributing/developer_guide.rst:70:<https://docs.pymc.io/api/distributions.html>`__), which divided into:

:ref:`api_distributions`

This also needs to create the api_distributions anchor in this file: https://github.com/pymc-devs/pymc/blob/main/docs/source/api/distributions.rst. That would be adding .. _api_distributions: in the first line (before the title)

docs/source/contributing/developer_guide.rst:323:   <https://docs.pymc.io/notebooks/api_quickstart.html#Automatic-transforms-of-bounded-RVs>`__.
docs/source/contributing/developer_guide.rst:329:   `doc <https://docs.pymc.io/notebooks/api_quickstart.html#Transformed-distributions-and-changes-of-variables>`__):
docs/source/contributing/developer_guide.rst:380:   transformation <https://docs.pymc.io/notebooks/api_quickstart.html?highlight=chain%20transformation>`__).

These need changes to the api quickstart notebook. I can do these changes and then I'll update with the references that should be used.

docs/source/contributing/developer_guide.rst:696:method <https://docs.pymc.io/notebooks/sampling_compound_step.html>`__.
docs/source/contributing/developer_guide.rst:699:RVs <https://docs.pymc.io/notebooks/sampling_compound_step.html?highlight=compoundstep#Specify-compound-steps>`__.
docs/source/contributing/developer_guide.rst:717:doc <https://docs.pymc.io/notebooks/sampling_compound_step.html#Specify-compound-steps>`__.

:ref:`nb:sampling_compound_step`  # or variations

this also needs updates to the notebook, will get back about them in a bit.

docs/source/contributing/developer_guide.rst:916:    -  `Using “black box” likelihood function by creating a custom Aesara Op <https://docs.pymc.io/notebooks/blackbox_external_likelihood.html>`__

:ref:`nb:blackbox_external_likelihood`

docs/source/contributing/release_checklist.md:25:+ Make sure the new version appears at the website and that [`docs.pymc.io/en/stable`](https://docs.pymc.io/en/stable) points to it.

This is actually a valid occurrence of the website 😱 can we skip this file from the checks maybe?

docs/source/index.md:158:Examples <https://docs.pymc.io/projects/examples/en/latest/>

:ref:`nb:index`

docs/source/learn/examples.md:6:- https://docs.pymc.io/en/stable/pymc-examples/examples/generalized_linear_models/GLM-linear.html

:ref:`nb:GLM-linear`

docs/source/learn/examples.md:9:- https://docs.pymc.io/en/stable/pymc-examples/examples/case_studies/multilevel_modeling.html

{ref}`nb:multilevel_modeling`  # note this is in a markdown file, so curly brackets instead of colons

docs/source/learn/examples.md:12:- https://docs.pymc.io/en/stable/pymc-examples/examples/diagnostics_and_criticism/model_comparison.html

{ref}`model_comparison`  # this has been moved from the examples so there should be no nb:

docs/source/learn/examples.md:16:- https://docs.pymc.io/en/stable/Probability_Distributions.html
docs/source/learn/examples.md:19:- https://docs.pymc.io/en/stable/PyMC3_and_Theano.html

I think these two files are gone 🤔

docs/source/learn/examples.md:23:- https://docs.pymc.io/en/stable/pymc-examples/examples/diagnostics_and_criticism/posterior_predictive.html

{ref}`posterior_predictive`   # also moved from examples, no nb:

docs/source/learn/examples.md:26:- https://docs.pymc.io/en/stable/Gaussian_Processes.html

{mod}`pymc.gp`

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[OriolAbril]

files to be excluded:

404
contributing/release_checklist
contributing/developer_guide
learn/examples.md

[OriolAbril]

docs/source/contributing/developer_guide_implementing_distribution.md:26:Before creating a new RandomVariable make sure that it is not offered in the Numpy library.

{mod}`numpy.random`

[OriolAbril]

docs/source/glossary.md:14: Choosing which function or method implementation to use based on the type of the input variables (usually just the first variable). For some examples, see Python's documentation for the singledispatch decorator.

{func}`~functools.singledispatch`

[symeneses]

files to be excluded:

404
contributing/release_checklist
contributing/developer_guide
learn/examples.md

After ignoring the files the check is passing.

[review-notebook-app]

View / edit / reply to this conversation on ReviewNB

OriolAbril commented on 2022-02-22T03:54:47Z
----------------------------------------------------------------

arviz:index

should be the target, meaning the index file out of the documentation mapped to arviz in intersphinx mapping.

[review-notebook-app]

View / edit / reply to this conversation on ReviewNB

OriolAbril commented on 2022-02-22T03:54:49Z
----------------------------------------------------------------

same here, arviz:index

You can see on the PR preview at https://pymc--5486.org.readthedocs.build/en/5486/learn/examples/pymc_overview.html#posterior-analysis that the cross reference isn't working like this. It is now searching for a file named arviz within the pymc documentation.

[OriolAbril]

Thanks @symeneses! ❤️