Improving xugrid docs with LLM help

[rsignell]

This is a bit of an embarrassing story, but for a long time I thought the xugrid docs were basically non-existent because I was only looking at the "index.html" page that ended with a pip installation instruction, but nothing really about usage over the quick example at the top. In other words, I didn't notice the "next" in the bottom right, or the "user guide" tab at the top. 🙃

Just in case others had the same issue, I forked the repo and asked Claude Code to create a top level page that looked more like the xarray docs page. Claude also suggesting a "how-to" guides page, so I said "sure" to see what it produced.

Here's what the "improved" docs look like:
https://opensciencecomputing.github.io/xugrid/index.html

What do you think? Is there anything useful there? I think I also accepted the suggestion to use markdown via Myst instead of straight RST.

Let me know if you would like some kind of PR or maybe just try a few prompts yourself to improve the index page?

[Huite]

Hi @rsignell,

That is indeed a little painful!

I think adding "how-to-guides" is a good idea, and adding the four cards in the grid does spruce up the index page a bit. In general, the more the docs resemble the xarray docs, the better.

I guess I'd skip the dev examples (they're a bit esoteric), so I think four good cards would be:

• Getting Started
• User Guide
• How to
• API Reference

The claude-code how to sections contain a number of good suggestions, but the scaling ones are basically just xarray. The assumption here is that people have some familiarity with xarray and are capable of navigating its documentation. I don't think replicating part of the xarray docs is desirable (although one could argue it makes the xugrid docs more readable); I think a good compromise is to insist regularly on the xarray documentation.

I'd be happy with a PR! I like acknowledging contributors (even if Claude Code did most of the heavy lifting!). We can take a few of the how-to's out and hopefully add a few.

I prefer straight RST over MyST. I don't think RST is bad enough (only a little unsightly) to warrant a conversion to MyST.

[rsignell]

Okay, sounds good. I'll take another stab at it taking into account your comments.