From be44b7b173b2aa853ebc3c35159ebbf7a3e9b3b6 Mon Sep 17 00:00:00 2001 From: Alexandre Andorra Date: Mon, 1 Apr 2024 09:59:50 -0300 Subject: [PATCH 1/6] Add link example --- docs/source/contributing/jupyter_style.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/contributing/jupyter_style.md b/docs/source/contributing/jupyter_style.md index 9dbfbd3def..676003bf0c 100644 --- a/docs/source/contributing/jupyter_style.md +++ b/docs/source/contributing/jupyter_style.md @@ -35,6 +35,8 @@ This guide does not teach nor cover MyST extensively, only gives some opinionate libraries documentations. Use [sphinx cross-references](https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html) instead. + * For instance, to link to another notebook, you could use an explicit link in the markdown text: "this model uses the \[Kronecker product](GP-Kron.myst.md)". This {ref}`this page ` for more details. + :::{caution} Using urls links breaks self referencing in versioned docs! And at the same time they are less robust than sphinx cross-references. From 6b8bf2540d7335e69edd7a9fe4ae64c4bdca0743 Mon Sep 17 00:00:00 2001 From: AlexAndorra Date: Mon, 1 Apr 2024 10:14:51 -0300 Subject: [PATCH 2/6] Fix typo --- docs/source/contributing/jupyter_style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/jupyter_style.md b/docs/source/contributing/jupyter_style.md index 676003bf0c..0a8860169e 100644 --- a/docs/source/contributing/jupyter_style.md +++ b/docs/source/contributing/jupyter_style.md @@ -35,7 +35,7 @@ This guide does not teach nor cover MyST extensively, only gives some opinionate libraries documentations. Use [sphinx cross-references](https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html) instead. - * For instance, to link to another notebook, you could use an explicit link in the markdown text: "this model uses the \[Kronecker product](GP-Kron.myst.md)". This {ref}`this page ` for more details. + * For instance, to link to another notebook, you could use an explicit link in the markdown text: "this model uses the \[Kronecker product](GP-Kron.myst.md)". See {ref}`this page ` for more details. :::{caution} Using urls links breaks self referencing in versioned docs! And at the same time they are From f5a674b91076b669d6fe3e87670e0d5a88a6ff88 Mon Sep 17 00:00:00 2001 From: AlexAndorra Date: Fri, 5 Apr 2024 18:33:07 -0300 Subject: [PATCH 3/6] Add Oriol's comments --- docs/source/contributing/jupyter_style.md | 31 +++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/source/contributing/jupyter_style.md b/docs/source/contributing/jupyter_style.md index 0a8860169e..2c38ae78c1 100644 --- a/docs/source/contributing/jupyter_style.md +++ b/docs/source/contributing/jupyter_style.md @@ -45,6 +45,37 @@ This guide does not teach nor cover MyST extensively, only gives some opinionate * When linking to other notebooks, always use a `ref` type cross-reference pointing to the target in the {ref}`jupyter_style_first_cell`. +* Here are more guidances on reference links: + +#### References to targets within the current project +That is, notebooks in pymc-examples referring to other notebooks in pymc-examples. + +``` +{ref}`explicit text ` +[explicit text](#anchor_id) +``` + +#### References to targets of other projects +These can be to any project defined in the [intersphinx mapping](https://github.com/pymc-devs/pymc-examples/blob/main/examples/conf.py#L175). For example, from pymc-examples to pymc main docs, or to arviz docs or to matplotlib docs; it doesn't matter when it comes to syntax. + +``` +{ref}`explicit text ` +[explicit text](inv:key:*:ref#anchor_id) +``` + +where key is one of the keys defined in the [intersphinx mapping](https://github.com/pymc-devs/pymc-examples/blob/main/examples/conf.py#L175), such as `pymc`, `arviz`, `numpy`... + +#### References to python objects + +``` +{type}`import.path` # to show full import path +{type}`~import.path` # to show only object name +``` + +where type is func for functions, meth for methods, class for classes, prop for property, etc. + +Now let's continue with the MysT guidelines. + * If the output (or even code and output) of a cell is not necessary to follow the notebook or it is very long and can break the flow of reading, consider hiding it with a {ref}`toggle button ` From d0b08e7492be7554b2c4c328c2cbc2e481f50d99 Mon Sep 17 00:00:00 2001 From: AlexAndorra Date: Fri, 28 Jun 2024 15:28:20 -0300 Subject: [PATCH 4/6] Add Oriol's comments --- docs/source/contributing/jupyter_style.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/source/contributing/jupyter_style.md b/docs/source/contributing/jupyter_style.md index 2c38ae78c1..800f008960 100644 --- a/docs/source/contributing/jupyter_style.md +++ b/docs/source/contributing/jupyter_style.md @@ -35,7 +35,7 @@ This guide does not teach nor cover MyST extensively, only gives some opinionate libraries documentations. Use [sphinx cross-references](https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html) instead. - * For instance, to link to another notebook, you could use an explicit link in the markdown text: "this model uses the \[Kronecker product](GP-Kron.myst.md)". See {ref}`this page ` for more details. + * For instance, to link to another notebook, you could use an explicit link in the markdown text: "this model uses the \{ref}`Kronecker product `". See {ref}`this page ` for more details. :::{caution} Using urls links breaks self referencing in versioned docs! And at the same time they are @@ -52,18 +52,23 @@ That is, notebooks in pymc-examples referring to other notebooks in pymc-example ``` {ref}`explicit text ` -[explicit text](#anchor_id) +``` +For instance: +``` +{ref}`Kronecker product ` ``` #### References to targets of other projects -These can be to any project defined in the [intersphinx mapping](https://github.com/pymc-devs/pymc-examples/blob/main/examples/conf.py#L175). For example, from pymc-examples to pymc main docs, or to arviz docs or to matplotlib docs; it doesn't matter when it comes to syntax. +These can be to any project defined in the [intersphinx mapping](https://github.com/pymc-devs/pymc/blob/main/docs/source/conf.py#L300-L312). For example, from pymc-examples to pymc main docs, or to arviz docs or to matplotlib docs; it doesn't matter when it comes to syntax. ``` {ref}`explicit text ` -[explicit text](inv:key:*:ref#anchor_id) ``` - -where key is one of the keys defined in the [intersphinx mapping](https://github.com/pymc-devs/pymc-examples/blob/main/examples/conf.py#L175), such as `pymc`, `arviz`, `numpy`... +where key is one of the keys defined in the [intersphinx mapping](https://github.com/pymc-devs/pymc/blob/main/docs/source/conf.py#L300-L312), such as `pymc`, `arviz`, `numpy`... +For instance: +``` +{ref}`ArviZ `plot_hdi` ` +``` #### References to python objects @@ -71,8 +76,11 @@ where key is one of the keys defined in the [intersphinx mapping](https://github {type}`import.path` # to show full import path {type}`~import.path` # to show only object name ``` - where type is func for functions, meth for methods, class for classes, prop for property, etc. +For instance: +``` +{class}`~pymc.gp.HSGP` +``` Now let's continue with the MysT guidelines. From 82909a9ff6fc39df779dc2151b2a8f60f6069c40 Mon Sep 17 00:00:00 2001 From: "Oriol (ProDesk)" Date: Mon, 1 Jul 2024 14:02:11 +0200 Subject: [PATCH 5/6] change rendering to fit into page --- docs/source/contributing/jupyter_style.md | 96 ++++++++++++++--------- 1 file changed, 58 insertions(+), 38 deletions(-) diff --git a/docs/source/contributing/jupyter_style.md b/docs/source/contributing/jupyter_style.md index 800f008960..7410b1246e 100644 --- a/docs/source/contributing/jupyter_style.md +++ b/docs/source/contributing/jupyter_style.md @@ -31,58 +31,78 @@ Using MyST allows taking advantage of all sphinx features from markdown cells in All markdown should be valid MyST (note that MyST is a superset of recommonmark). This guide does not teach nor cover MyST extensively, only gives some opinionated guidelines. -* **Never** use url links to refer to other notebooks, PyMC documentation or other python - libraries documentations. Use [sphinx cross-references](https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html) - instead. - - * For instance, to link to another notebook, you could use an explicit link in the markdown text: "this model uses the \{ref}`Kronecker product `". See {ref}`this page ` for more details. +* **Never** use url links to refer to other notebooks, PyMC documentation or other python libraries documentations. + When linking to other notebooks, always use a `ref` type cross-reference pointing to the target in the {ref}`jupyter_style_first_cell`. :::{caution} Using urls links breaks self referencing in versioned docs! And at the same time they are less robust than sphinx cross-references. ::: - * When linking to other notebooks, always use a `ref` type cross-reference pointing - to the target in the {ref}`jupyter_style_first_cell`. + ::::{dropdown} Examples of cross-references -* Here are more guidances on reference links: + **References to targets within the current project** -#### References to targets within the current project -That is, notebooks in pymc-examples referring to other notebooks in pymc-examples. + That is, notebooks in pymc-examples referring to other notebooks in pymc-examples. -``` -{ref}`explicit text ` -``` -For instance: -``` -{ref}`Kronecker product ` -``` + Pattern: + ``` + {ref}`explicit text ` + ``` + + Example source: + ``` + {ref}`Kronecker product ` + ``` -#### References to targets of other projects -These can be to any project defined in the [intersphinx mapping](https://github.com/pymc-devs/pymc/blob/main/docs/source/conf.py#L300-L312). For example, from pymc-examples to pymc main docs, or to arviz docs or to matplotlib docs; it doesn't matter when it comes to syntax. + Rendered example: {ref}`Kronecker product ` -``` -{ref}`explicit text ` -``` -where key is one of the keys defined in the [intersphinx mapping](https://github.com/pymc-devs/pymc/blob/main/docs/source/conf.py#L300-L312), such as `pymc`, `arviz`, `numpy`... -For instance: -``` -{ref}`ArviZ `plot_hdi` ` -``` + **References to targets of other projects** -#### References to python objects + Here "other projects" means any sphinx documentation site that was build independently + of the current one. Therefore, this includes linking to pymc-examples notebooks + from the pymc documentation or vice versa, or linking to other libraries like + arviz, numpy, matplotlib... -``` -{type}`import.path` # to show full import path -{type}`~import.path` # to show only object name -``` -where type is func for functions, meth for methods, class for classes, prop for property, etc. -For instance: -``` -{class}`~pymc.gp.HSGP` -``` + Pattern: + ``` + {ref}`explicit text ` + ``` + Example source: + ``` + {ref}`how to use InferenceData ` + ``` + + Rendered example: {ref}`how to use InferenceData ` + + where `key` in the pattern (`arviz` in the example) is one of the keys defined in + the `intersphinx_mapping` variable of `conf.py` such as `arviz`, `numpy`, `mpl`... + For the main pymc repo it is located in `docs/source/conf.py`, for pymc-examples it is + in `examples/conf.py`. + + **References to python objects** + + Pattern + ``` + {type}`import.path` # to show full import path + {type}`~import.path` # to show only object name + ``` + where type is func for functions, meth for methods, class for classes, prop for property, etc. + + Example source: + ``` + {class}`~pymc.gp.HSGP` + ``` + + Rendered example: {class}`~pymc.gp.HSGP` + + + :::{seealso} + * [ReadTheDocs page on sphinx cross-references](https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html) instead. + * {ref}`MyST docs on cross-references `. + ::: + :::: -Now let's continue with the MysT guidelines. * If the output (or even code and output) of a cell is not necessary to follow the notebook or it is very long and can break the flow of reading, consider hiding From 022fd986e65ba11e58101a46be93f2cc1ad6fcab Mon Sep 17 00:00:00 2001 From: AlexAndorra Date: Mon, 1 Jul 2024 18:01:52 -0300 Subject: [PATCH 6/6] Add how to identify anchor_id --- docs/source/contributing/jupyter_style.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/contributing/jupyter_style.md b/docs/source/contributing/jupyter_style.md index 7410b1246e..e935fd00a7 100644 --- a/docs/source/contributing/jupyter_style.md +++ b/docs/source/contributing/jupyter_style.md @@ -80,6 +80,8 @@ This guide does not teach nor cover MyST extensively, only gives some opinionate For the main pymc repo it is located in `docs/source/conf.py`, for pymc-examples it is in `examples/conf.py`. + To identify which `anchor_id` to use, you need to either look at the source of the document, or use [sphobjinv](https://sphobjinv.readthedocs.io/en/stable/). + **References to python objects** Pattern