Skip to content

add API reference links #2442

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.

Sign up for GitHub

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

Jump to bottom
Merged
VeckoTheGecko merged 10 commits into from
Jan 13, 2026
Merged

add API reference links #2442

VeckoTheGecko merged 10 commits into from
Jan 13, 2026

Conversation

@reint-fischer
Copy link
Contributor

@reint-fischer reint-fischer commented Dec 19, 2025 •
edited by VeckoTheGecko
Loading

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.

Sign in to view
@VeckoTheGecko

This comment was marked as outdated.

Sign in to view
@erikvansebille
Copy link
Member

erikvansebille commented Jan 5, 2026

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 VeckoTheGecko mentioned this pull request Jan 5, 2026
Closed
@erikvansebille erikvansebille mentioned this pull request Jan 12, 2026
Merged
@VeckoTheGecko
Copy link
Contributor

VeckoTheGecko commented Jan 12, 2026 •
edited
Loading

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

erikvansebille commented Jan 12, 2026

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
@VeckoTheGecko VeckoTheGecko mentioned this pull request Jan 13, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@erikvansebille erikvansebille erikvansebille approved these changes

Assignees

No one assigned

Labels

None yet

Projects

Parcels development
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@reint-fischer @VeckoTheGecko @erikvansebille