Skip to content

DOC: Add open source diagram tooling #2532

@VeckoTheGecko

Description

@VeckoTheGecko

I think our documentation can benefit from having diagrams to help explain certain concepts. There's the general setup of Parcels, which already has a diagram, but other concepts which might benefit are:

  • The concept of chunking (which is important when it comes to working with xarray)
  • The concept of SGRID
  • (potentially) some stuff on the unstructured grid side

With these diagrams, however, they should be easy to edit with open source tooling. That is a major consideration, as it means that they can be easily editted down the line.

Stylistically I'm a huge fan of excalidraw, but that may be too simple (i.e., have the flexibility that we would need, it only allows for simpler shapes).

Another option is draw.io - which was used to create the original diagram of the layout of parcels (I like this a bit less)

What do you think @erikvansebille ? (if you're keen for diagraming tooling - perhaps have a play with those linked above, or see if there are other open source diagraming tools that you like)

When it comes to integrating these into the documentation, I have the following in mind:

(using excalidraw as an example)

  • Store the source files (e.g.,) sgrid.excalidraw in a docs/assets/excalidraw folder
  • Use a Pixi task to automatically build these into PDF files (this is automatically run during the docs process)
  • Use the PDF outputs and embed into website

Metadata

Metadata

Assignees

Type

No type
No fields configured for issues without a type.

Projects

Status

Backlog

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions