OriolAbril
commented
3 months ago There are now multiple ways to specify cross-references with myst. I agree it is a good idea to list examples of the common ones. It doesn't really change between pymc and other project, but it does between documentation pages/sections and python objects listed in the API docs (independently of the project), so I updated the 3 cases.
Here are some options, let's see which is generally thought as more intuitive. I prefer the 1st because it is closer to rst (which we still use for docstrings so less extra things to learn) and it is also closer to citation syntax in pymc-examples, but it's not a very strong preference.
References to targets within the current project
That is, notebooks in pymc-examples referring to other notebooks in pymc-examples.
Explicit text
{ref}`explicit text <anchor_id>`
[explicit text](#anchor_id)I haven't extensively tried the 2nd one though, so not sure how well it will work, I think it gives preference to implicit targets within the file over explicit targets on other files, but IIRC pymc-examples is configured to not generate any implicit target.
Implicit text
in which case the notebook title is used as text for the link.
{ref}`anchor_id`
<project:#anchor_id>
[](#anchor_id)References to targets of other projects
These can be to any project defined in the intersphinx_mapping. For example, from pymc-examples to pymc main docs, or to arviz docs or to matplotlib docs; doesn't matter where when it comes to syntax.
Explicit text
{ref}`explicit text <key:anchor_id>`
[explicit text](inv:key:*:ref#anchor_id)Implicit text
{ref}`key:anchor_id`
[](inv:key:*:ref#anchor_id)
<inv:key:*:ref#anchor_id>where key is one of the keys defined in the intersphinx mapping 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
{type}`custom text <import.path>` # to show other text (not recommended)where type is func for functions, meth for methods, class for classes, prop for property... These don't use the myst syntax even if possible and more markdown-y because when doing that the generated links are rendered with regular font, not with monospaced font.
doc type references (those that use paths within a project) like the one used in the current example should be avoided and I think they should therefore not have an example here. Notebooks are moved, extended, splitted in two, renamed, removed, merged... which makes path based links very brittle, reference links on the other hand will still work as long as the update keeps the anchor (and a notebook can have multiple anchors, so merging is not an issue, see for example https://github.com/pymc-devs/pymc-examples/blob/main/examples/generalized_linear_models/multilevel_modeling.ipynb)
daniel-saunders-phil
AlexAndorra
ricardoV94
The Jupyter style guide is adamant that we should "never use url links to refer to other notebooks, PyMC documentation or other python libraries", but doesn't provide clear examples for how to do it IMO -- it just took me quite some time to somewhat understand how to do it.
I think adding a small example for at least each of these three very common use-cases would go a long way into onboarding new contributors and making their lives easier.
I added what I think is a right example of referring to another notebook, but will be very happy for your review @OriolAbril 😅 Could you also suggest a small example of how to reference PyMC documentation and another python library?
TODO
Type of change
📚 Documentation preview 📚: https://pymc--7235.org.readthedocs.build/en/7235/