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

Projects

Status

Backlog

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions