Documentation structure v4 #2349

reint-fischer · 2025-10-28T11:02:34Z

Implements proposed changes from #2310

Major changes

Separate “Getting Started” from “User Guide”
Separate and bring forward “Contributing” and “Community” pages

Notes

In my current view, the strength of our documentation has always been the extended Jupyter Notebooks; tutorials, which I think we should call “How-to guides”, because they are for advanced users and typically answer a “how to?” such as “How to write a Kernel which encodes ARGO behavior?” or “How to set up a FieldSet with a Curvilinear grid?”. I think we should keep this strength, and put it within a “User guide”, which includes beginner tutorials and explanation (.md files) of important Parcels concepts. See Divio for an extended description of the differences between tutorials, explanations, and how-to guides.

TODO:

Outline parcels concepts explanation
Add docstring rules to per-file ruff lint
Add Lagrangian Diagnostics to community

Fixes #2302

…on, and how-to guides

VeckoTheGecko · 2025-10-30T11:25:28Z

Looks like great progress! Happy to do a full review when ready.

Note that this badge does not work (its linking to the website instead - likely because clicking anywhere in the card links to the website). Maybe you can link to the Zulip using a button like for the GitHub?

The Zulip badge was mainly for the README

reint-fischer · 2025-10-30T11:45:03Z

Thanks Nick! I have fixed the Zulip badge which should work now. I am considering requesting a full review now, as the next things I want to look into are the Reference API and how to outline the Parcels concept explanation files, see main PR message. I could work on those separately from this PR? Or I can wait for your initial review and work on those later and switch to some other tasks for the moment?

VeckoTheGecko · 2025-10-30T15:29:31Z

I could work on those separately from this PR?

I think that would be best. Its easier if I can review these changes - get them merged, and then get the other changes merged via another PR (otherwise this PR gets too large, or I have to re-review which is difficult)

VeckoTheGecko · 2025-10-31T08:24:31Z

(re-triggering CI)

VeckoTheGecko · 2025-10-31T08:26:50Z

pixi.toml

 sphinx-autobuild = "*"
 myst-parser = "*"
 sphinxcontrib-mermaid = "*"
+sphinx-design = "*"


I assume this is used for the grid? Happy to add

VeckoTheGecko · 2025-10-31T08:28:04Z

pyproject.toml


+[tool.ruff.lint.per-file-ignores]
+# Ignore docstring rules everywhere except for the stable files (particleset.py).
+"!src/parcels/_core/{particleset}.py" = [
+  # Missing docstring in public module
+  "D100",
+  # Missing docstring in public class
+  "D101",
+  # Missing docstring in public method
+  "D102",
+  # Missing docstring in public function
+  "D103",
+]


Looks good. Up to you whether you'd like to manage this in the same file this way, or via a separate file - either works

Thanks, I will move this to a new PR however, where we can implement the Reference API more thoroughly.

VeckoTheGecko · 2025-10-31T08:29:04Z

docs/conf.py

 # epub_use_index = True
+
+# -- Options for MyST parser ----------------------------------------------
+myst_heading_anchors = 3


This is great

docs/conf.py

docs/community/index.md

VeckoTheGecko · 2025-10-31T08:51:22Z

docs/index.md

+Getting started <getting_started/index>
+Documentation <user_guide/index>
+Community <community/index>
+Contributing <contributing/index>
 API reference <reference>
-Contributing, Release Notes and more <community/index>
 Parcels website <https://parcels-code.org/>


From the card - I assume the "Getting started" section still needs the quickstart tutorial?

I like the split of "Getting Started" from the rest of the user guide.

I wouldn't mind more sprinkling of TODO comments/note blocks in the documentation (e.g., creating an empty quickstart page with "TODO") to signpost the future development. This makes it easier to review - to have an idea for the structure that you have in mind in a way that is surfaced directly in the website, since at the moment I need to pull from context (e.g., I only deduced that the Quickstart tutorial was planned for the "Getting Started" section via the card on the homepage).

Something like

 ```{note} TODO: Write quickstart tutorial. This should focus on .... ```

Creating such empty files that need to be filled out is a nice workflow I think - scaffolding things out

Good idea, thank you!

I have started on some of the tutorials in other PRs, so I will also merge those in, but there is still quite some scaffolding which will be useful

VeckoTheGecko · 2025-10-31T08:52:36Z

docs/index.md

+Getting started <getting_started/index>
+Documentation <user_guide/index>
+Community <community/index>
+Contributing <contributing/index>


Maybe we should rename Contributing to Development, as that encompasses the different pages inside

Contributing Guidelines Versioning Policy Release Notes Maintainers notes

I like that a lot!

VeckoTheGecko · 2025-10-31T09:04:28Z

docs/user_guide/index.md

+:hidden:
+v3 to v4 migration guide <v4-migration>
+Example scripts <additional_examples>
+Community examples <https://github.com/Parcels-code/parcels_contributions>


Given the current maintenance status of parcels_contributions, I don't think that we should promote this here in the sidebar. I think its important to distinguish it as a separate project - happy to just reference it in the community section.

VeckoTheGecko · 2025-10-31T13:15:42Z

Reminder @reint-fischer : If you want this PR to automatically close any issues on merge, you can put fixes #1234 (or "resolves", or "closes") in the PR body.

For multiple: fixes #1, fixes #2, fixes #3 etc.

Wasn't sure if you wanted this to close #2310 - just thought I'd mention

GitHub docs: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword

Co-authored-by: Nick Hodgskin <[email protected]>

VeckoTheGecko · 2025-11-03T15:04:33Z

docs/getting_started/installation.md

 conda activate parcels
 ```

 **Step 4:** Download [a zipped copy](https://docs.parcels-code.org/en/latest/_downloads/307c382eb1813dc691e8a80d6c0098f7/parcels_tutorials.zip) of the Parcels tutorials and examples and unzip it.


Since #2293 this step 4 is outdated and can be removed

And I assume step 5 is too then right?

…s more visible

…utorial/documentation naming split This reverts commit 2d49457.

…uide

reint-fischer · 2025-11-04T16:21:17Z

From the card - I assume the "Getting started" section still needs the quickstart tutorial?

I like the split of "Getting Started" from the rest of the user guide.

I wouldn't mind more sprinkling of TODO comments/note blocks in the documentation (e.g., creating an empty quickstart page with "TODO") to signpost the future development. This makes it easier to review - to have an idea for the structure that you have in mind in a way that is surfaced directly in the website, since at the moment I need to pull from context (e.g., I only deduced that the Quickstart tutorial was planned for the "Getting Started" section via the card on the homepage).

Something like

```{note}
TODO: Write quickstart tutorial. This should focus on ....
Creating such empty files that need to be filled out is a nice workflow I think - scaffolding things out

I have now added some scaffolding which would improve navigation and helps visualise TODO items, but I realised that splitting out notebooks over multiple folders, instead of having them in one “examples” folder, might complicate testing them. Depending on what we decide in #2335 , this might not be such a big problem, but we should figure it out before merging this.

for more information, see https://pre-commit.ci

…der.

…ls-code/Parcels into documentation-structure-v4 pre-commit changes

…ture-v4 resolved changes to documentation folder structure

reint-fischer added 5 commits October 27, 2025 15:34

implement new documentation structure as per #2310

9533fdd

fix some links

f7d1027

restructure homepage

d56f00f

update community page

766d409

fix some toctrees

fa25497

github-project-automation bot added this to Parcels development Oct 28, 2025

github-project-automation bot moved this to Backlog in Parcels development Oct 28, 2025

reint-fischer marked this pull request as draft October 28, 2025 11:12

reint-fischer changed the title ~~Documentation structure v4 DRAFT~~ Documentation structure v4 Oct 28, 2025

This was referenced Oct 28, 2025

Rename to “Community Kernels” or “user examples”? Parcels-code/parcels_contributions#14

Open

Link in documentation to parcels_contributions #2302

Closed

reint-fischer and others added 2 commits October 28, 2025 15:50

rename documentation to user guide, consisting of tutorial, explanati…

08c29ab

…on, and how-to guides

add LA Diag and Zulip logos

0c8eacd

reint-fischer mentioned this pull request Oct 29, 2025

Zulip badge #2336

Open

reint-fischer added 2 commits October 30, 2025 09:57

move examples under user_guide

1a31565

introduce per-file docstring rules to apply to stable v4 code

71096a9

fix Zulip link

ac81305

reint-fischer requested a review from VeckoTheGecko October 30, 2025 12:40

VeckoTheGecko marked this pull request as ready for review October 30, 2025 15:29

VeckoTheGecko closed this Oct 31, 2025

github-project-automation bot moved this from Backlog to Done in Parcels development Oct 31, 2025

VeckoTheGecko reopened this Oct 31, 2025

github-project-automation bot moved this from Done to Backlog in Parcels development Oct 31, 2025

VeckoTheGecko requested changes Oct 31, 2025

View reviewed changes

github-project-automation bot moved this from Backlog to Ready in Parcels development Oct 31, 2025

VeckoTheGecko mentioned this pull request Oct 31, 2025

Fix pixi version within Pixi cache workflow #2351

Merged

VeckoTheGecko force-pushed the documentation-structure-v4 branch from e409fc1 to ac81305 Compare October 31, 2025 11:20

reint-fischer and others added 4 commits November 3, 2025 11:22

Link to GitHub image

902f3d5

Co-authored-by: Nick Hodgskin <[email protected]>

rename "contributing" to "development"

9bb0ea6

remove parcels_contributing from sidebar

3b48b95

start scaffolding getting_started and user_guide

2d49457

reint-fischer force-pushed the documentation-structure-v4 branch from 63bccc1 to 2d49457 Compare November 3, 2025 14:12

add some more scaffolding

355cde0

VeckoTheGecko reviewed Nov 3, 2025

View reviewed changes

reint-fischer added 7 commits November 3, 2025 16:48

remove some superfluous text and links

e305182

restore ruff lint ignore

93f9aca

change nav bar to make community, development, and API reference page…

b4bd7ff

…s more visible

Revert "start scaffolding getting_started and user_guide" to retain t…

fe9defc

…utorial/documentation naming split This reverts commit 2d49457.

Fix navigation by adding scaffolding pages

7473293

add documentation notes to outline ideas for docs website and style g…

6cc21ea

…uide

update notebook testing folder

0626bee

reint-fischer mentioned this pull request Nov 4, 2025

Handling of tutorial notebook cell outputs in v4 #2335

Open

reint-fischer and others added 7 commits November 5, 2025 13:00

Merge branch 'v4-dev' into documentation-structure-v4

5749f57

[pre-commit.ci] auto fixes from pre-commit.com hooks

8a429b7

for more information, see https://pre-commit.ci

make quickstart tutorial a .md file to keep notebooks in examples fol…

2d1ec99

…der.

Merge branch 'documentation-structure-v4' of https://github.com/Parce…

3039320

…ls-code/Parcels into documentation-structure-v4 pre-commit changes

Merge remote-tracking branch 'origin/v4-dev' into documentation-struc…

face255

…ture-v4 resolved changes to documentation folder structure

fix TrajAn link

2bfef2f

add LA Diag Cookbook link at the top of output tutorial

3f884fd

VeckoTheGecko approved these changes Nov 5, 2025

View reviewed changes

reint-fischer merged commit bba37f4 into v4-dev Nov 5, 2025
10 of 11 checks passed

reint-fischer deleted the documentation-structure-v4 branch November 5, 2025 14:28

github-project-automation bot moved this from Backlog to Done in Parcels development Nov 5, 2025

reint-fischer mentioned this pull request Nov 5, 2025

Documentation restructure #2310

Closed

Documentation structure v4 #2349

Documentation structure v4 #2349

Uh oh!

Conversation

reint-fischer commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Major changes

Notes

TODO:

Uh oh!

VeckoTheGecko commented Oct 30, 2025

Uh oh!

reint-fischer commented Oct 30, 2025

Uh oh!

VeckoTheGecko commented Oct 30, 2025

Uh oh!

VeckoTheGecko commented Oct 31, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

VeckoTheGecko Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

VeckoTheGecko commented Oct 31, 2025

Uh oh!

VeckoTheGecko Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

reint-fischer commented Nov 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

reint-fischer commented Oct 28, 2025 •

edited

Loading

VeckoTheGecko Oct 31, 2025 •

edited

Loading

VeckoTheGecko Nov 3, 2025 •

edited

Loading