ProjectPythia / ProjectPythia/pythia-foundations
Making better use of cross-referencing
Nobody has claimed this yet.
- Dominant language
- Jupyter Notebook
- Stars
- 72
- Forks
- 60
- Avg merge
- 17h 36m
- Merged PRs (30d)
- 2
Description
As discussed in #609, there is quite a bit of scope for making better use of Myst capabilities for cross-referencing with external documentation.
We are currently defining some site-wide references in our upstream config file to a few sets of documentation including Xarray, Matplotlib, and our own Foundations.
It would be possible to go through the book and replace a lot of full URL links to documentation pages with cross-references. And example is in the overview section of the Xarray intro notebook.
One advantage of doing this would be more stable links. If an upstream doc site reorganizes its URLs, as long as the intersphinx references stay put, the links in our book will still resolve correctly.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the discussion in #609, the upstream pythia.yml references, and the example in core/xarray/xarray-intro.ipynb. Review the book for full documentation URLs that can use the configured cross-references, then verify that the converted links resolve and remain stable through the site-wide references.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- jupyter-notebook
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100