Big docs reorganise and expand.

[pp-mo]

Closes #80
Refactored version of #105

Adds new sections on core data and general operations.
Integrates the how-to sections also

Todos:

• prune for repetition.
• review + clarify 4-way Diataxis-like top-level division =
  • Getting Started (intro + tutorial)
  • User Guide
  • API
  • Detail Notes
• move existing details sections to "detail notes" sections (possibly with short hinting links)
• add a how-to on chunking control
• review for changes to equality provision (no comprehensive == on variable/ncdata)
• re-proof-read all

[pp-mo]

@trexfeathers welcome and thanks for looking !
if reviewing, scope here is really : do the docs structure and coverage generally look appropriate to you now (as a first proper attempt). i.e. notably

• are there things badly misplaced
• or plain missing
• is it clear enough from the entry point level what is available + where to find things

Great also to have anyone else comment on this,
I think it's the only thing really needed now prior to v0.2 release (except release whatsnew drafting)

[pp-mo]

OK I have now reviewed all the API docs builds, fixed (hopefully) for correctness and updated, generally smoothed over and introduced some more cross-links into newer docs sections where it seemed obvious.

So I reckon this is up to scratch now, pending any suggestions about structural improvements.

[trexfeathers]

OK I've read most of it. It is impressively comprehensive 💐

To-do for @trexfeathers:

• Review the details section
• Consider the overall structure/approachability

[trexfeathers]

Here is the rest of my review.

General thoughts

I think this is some of the most complete documentation we have, because it caters to all the different types of readers.

It is laid out in an approachable way that is also low maintenance, so I'm happy to merge with the current structure 👍👍👍

However

Given the excellent breadth of 'all-angles' content, it feels like a missed opportunity to not go all-in on Diataxis. From offline conversations this sounds deliberate, but I'm hoping we can come back in future to 'finish the job'?

[pp-mo]

Progress : New commit pp-mo@3433c29 covers, I think, all the "original" review comments
- and just a couple of the newer set
I have to stop now, and it makes a good point to pause.

Meanwhile I start to think about the "newer set" of suggestions

[pp-mo]

@trexfeathers thanks for your careful attention !
I think I've now addressed all-to-date

Probable exceptions, issues you've raised which I think I want to "pin" for now :

• recognise diataxis explicitly
• consider rename, replace or remove the "set_attrname" and "get_attrname" methods
• update changenotes including release version Complete changenotes for v0.2 #115

Please check it out + see what you think.

On inspection, I think I probably don't need to merge from main before completing this (read on...)
So easier for you to check it all out as-is without further re-hash, and I'll merge from main later.

Differences currently waiting on main are only those from #112, to do with unpinning numpy to v2. Associated changes affect array printout and its tests. That does not create major problems here, as changes here are all docs with no functional effect.
It may affect some code examples, but as they don't run as doctests, we will only find that later by looking.
Not exactly a good thing, but not a merge blocker !

[pp-mo]

Hang on ....

I just realised the initial "Introduction" tutorial has chunks of code that ought to be in rst "code-block"s.
Left-overs from my initial ignorance.
I will attend to that ...

[pp-mo]

Hang on ....

I just realised the initial "Introduction" tutorial has chunks of code that ought to be in rst "code-block"s. Left-overs from my initial ignorance. I will attend to that ...

OK done that. Not sure what else I'm still missing at the last minute though 😥

[trexfeathers]

This is great! We're down to 4 outstanding options, plus a final 5th conversation that needs no action.

[trexfeathers]

Super! Thanks @pp-mo

[pp-mo]

Awesome, thanks for all your effort. 🥇
I'll try to be more incremental in future !