Skip to content

Conversation

@reint-fischer
Copy link
Contributor

@reint-fischer reint-fischer commented Dec 19, 2025

This PR adds API reference links throughout the documentation, which resolves a TODO note.

Since we use sphinx autoapi (#2395) to build the API reference, and MyST to parse markdown (#1342), we should use the {py:obj} role to refer to parcels objects (see executablebooks/discussions/q-a#1169)

e.g.:

{py:obj}`parcels.FieldSet`

Unfortunately, I am only able to refer to classes, and not their methods, i.e. the following doesn’t create the link to the method:

{py:meth}`parcels.ParticleSet.execute()`

See also: https://www.sphinx-doc.org/en/master/usage/domains/python.html#role-py-meth

Work done (contributing to #2449) :

@VeckoTheGecko

This comment was marked as outdated.

@VeckoTheGecko

This comment was marked as outdated.

@erikvansebille
Copy link
Member

Should I make this into a separate issue to be pursued later @erikvansebille ? I think cross linking with the classes is suitable for now/a bit lower on the chopping block

Yep, I don't think this is a priority now

VeckoTheGecko and others added 2 commits January 12, 2026 15:01
Co-authored-by: Erik van Sebille <erikvansebille@gmail.com>
Fixes #2448
@VeckoTheGecko
Copy link
Contributor

VeckoTheGecko commented Jan 12, 2026

Is there anything we're waiting on @erikvansebille before merging this?

I think it would be good to update the contributing guidelines at some point with

  • Decide on English spelling rules (and add to docsguide)? #2376
  • Mentioning that you can do {py:meth}`parcels.FieldSet.from_copernicusmarine to show parcels.FieldSet.from_copernicusmarine OR you can shorten it with {py:meth}`~parcels.FieldSet.from_copernicusmarine to show from_copernicusmarine
  • Guidance on whether to crosslink all the time, or just on first mention (up to us to decide - though perhaps all the time would be nice so that we avoid broken docs down the line if things don't get updated)

I think this sort of guidance can be done as a mention in the current docs/development/index.md

@erikvansebille
Copy link
Member

No I think ti's good to go. Feel free to merge!

@VeckoTheGecko VeckoTheGecko enabled auto-merge (squash) January 13, 2026 09:44
@VeckoTheGecko VeckoTheGecko merged commit 99e6d18 into v4-dev Jan 13, 2026
9 of 10 checks passed
@VeckoTheGecko VeckoTheGecko deleted the reference-API-links branch January 13, 2026 09:49
@github-project-automation github-project-automation bot moved this from Backlog to Done in Parcels development Jan 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

4 participants