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
Add Myst cross reference link example to Jupyter style guide #7235
base: main
Are you sure you want to change the base?
Conversation
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 projectThat is, notebooks in pymc-examples referring to other notebooks in pymc-examples. Explicit text
I haven't extensively tried the 2nd one though, so not sure how well it will work, I think it gives Implicit textin which case the notebook title is used as text for the link.
References to targets of other projectsThese 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
Implicit text
where key is one of the keys defined in the intersphinx mapping such as References to python objects
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) |
This is a great idea. I've struggled a bit with the juypter style guide on references so this would really help. I like explicit texts for first two and
for the third. |
Fantastic, thanks @OriolAbril ! I just added these guidelines to the file, opting for explicit texts. |
we can choose explicit text over implicit text and only show examples of explicit text, but we really have to choose one option within each code block (excluding the last one for python objects). Generating links with explicit or implicit text are conceptually different things, so it is not as confusing to newcomers (and in general) to have different ways to generate the cross-references. But all options within the same code block do exactly the same, which can be confusing by itself, but even more when both are used in multiple places and it isn't clear why or if there even is a difference between them. Preferring cross-references with explicit text over ones with implicit text, that means the choice is between one of these two:
and then also one of these two:
I wasn't very clear before, but with that I meant I prefer the first option within each code block, thus:
But I know the other is closer to markdown link syntax and markdown is generally preferred over rST. |
Oh oh I see what you meant. Yeah the {ref}’’ ones are better. Fits with expectations you learn from the docstrings which is a big help. |
If it weren't for the weird inv key *, I would vote for markdown |
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/