Revamp of documentation based on new user feedback.

[acchamber]

From a discussion at AVD surgery, There's a few changes I think would make Iris more accessible to new users, based of mine and other new starters experiences in the Programmes Directorate over the past year.

• Integrate the Gallery section more tightly into the user guide - link to a relevant gallery example in some sections and examples if one exists

  • Also might be worth refreshing the examples - did they all get their imports checked for the lazy_loader change?

• Add more examples to the user guide, and additions to some sections based on tasks users have tried to do and struggled in figuring out how to do,

  • Some of this can be taken or adapted from the old training notebooks for Iris/Numpy eg: What's a masked array and how do I work with it?
  • These course notebooks still have working binder instances - are they worth promoting more widely?

• A Further Topics section on creation/modification of Aux Coord factories, as there's very little available on using them at the moment

Any comments on whether they are good ideas or not, or other suggestions are appreciated, I hope to implement some of these over the summer.

[pp-mo]

the examples - did they all get their imports checked ... ?

The examples execute as doctests via 'test wrapper' routines, which continuously ensures they don't error.
E.G. this one.

In principle there is also support to ensure that they don't throw warnings, either -- principally to check that we remove any deprecated calls.

It does look like that idea may have gone a bit stale though, e.g. this one doesn't do it.
It would be a good idea to replace the 'boilerplate' code in these tests - -scope for a "good first time PR" ?

[rcomer]

It would be a good idea to replace the 'boilerplate' code in these tests

I had thought about using pytest parametrization for the gallery tests so that we can just write it once. Probably not possible with our current bespoke graphics tests but I assume should be straightforward if/when we adopt pytest-mpl.

[pp-mo]

@rcomer I had thought about using pytest parametrization for the gallery tests so that we can just write it once. Probably not possible with our current bespoke graphics tests but I assume should be straightforward if/when we adopt pytest-mpl.

Using a PyTest fixture could certainly reduce the boilerplate duplication, but at present we will still need to manually provide a separate 'test_xxx.py' to wrap each example script.
I don't think the example scripts can themselves simply "be" pytest tests, so this remains.

Can someone see a neat way to automate that ?

[rcomer]

Sometimes I get an idea in my head and just can't help myself... #4792

It turned out to be a lot easier than I feared to extricate the graphics checking from the Iris test class.

[rcomer]

the examples - did they all get their imports checked ... ?

The examples execute as doctests...

I didn't realise at first, but this actually is a good question: we have several examples that use iris.cube and/or iris.coords without explicitly importing that module. It all works just fine (and the tests pass) because something happened up script to import the module behind the scenes. But we have advised here that you shouldn't be relying on that sort of thing.

plot_polynomial_fit
plot_custom_file_loading
plot_lagged_ensemble
plot_coriolis

[wjbenfold]

I've made an issue encouraging more linking between the docs and the gallery, it seems a great place to start.

Any information you have on which aspects of Iris people have more trouble working out how to use would be great - either by raising issues or making those fixes yourselves. We don't get much feedback of that type from users so frequently don't know where to direct our efforts in that regard.

Do you have suggestions on who we can promote the notebooks to? Is that something you can pass to someone in the right sort of place?

I think a more thorough revamp of the docs to have tutorials distinct from how-tos would help the userguide to be more helpful for everyone, as currently it's torn between not going too deep and not staying too shallow.

An additional further topics section also seems a great place to start. Feel free to write it or raise an issue suggesting it (or both!)

[acchamber]

Often, it's not that iris doesn't work - it's just that scientists don't know how to use it effectively for their tasks. I'm gathering feedback from people I know, but I'd say a general problem is that the examples in the user guide don't cover the common use-cases we have in Programmes when working with climate data. That's a fuzzy problem to fix though, so I'm trying to pin down some clearer aims before putting them to paper.

The problem is that current "new starter" technical development is more fragmented than it was pre-covid - often a Pluralsight license is the first port of call, and then individual managers pointing them to the iris user guide or learning from code that already exists for the project the new starter is going to start work on. There's no one place I can think of, but if managers were aware of them they might be more widely used. In the mean time I can at least promote them to those who use them.

I think that a more thorough revamp would be ideal, but we rarely get the ideal. Another idea I have had raised to me in discussion is an iris "cheat sheet" or single-page reference in the docs, which I'm playing with working on.

On Further Topics, I've added issues for two I've personally worked with and would benefit from more detail - aux factories and iris.analysis (it can do alot more than MAX/MIN/MEAN on collapse, but there's very little awareness of it or how to use it). If someone else took them up I'd be delighted, but even if not raising the issues still should be useful.