minor improvement on documentation "Loading Iris Cubes.rst" #6232
Conversation
|
|
There was a problem hiding this comment.
Hey @Qinqing-Li,
Thank you so much for getting involved! We really appreciate external collaborators taking the time to help improve Iris!
I'm a bit uncertain of the motivation behind this pull request. What made you decide to change the existing docs? A lot of the changes you've made don't necessarily make sense to me, would you mind explaining them?
If you believe your changes are important and improve the quality of the documentation, please don't get discouraged, and feel free to disagree with my comments!
If you're wanting to contribute to Iris generally, there are a number of easier entry points:
- Convert tests from unittest to pytest #6212: We're in the process of converting our tests from
unitteststyle topytest. We have some handy documentation here and here. Contributing a file or two (or more) would be a huge help, and I'd do my best to support you in this. - We have plenty of docstrings in our code, and some of them could do with some code examples added to them. If you're interested in this, I'd have a look at some of our existing docstring examples, and then use those as a template to make your own additions.
- Finally, you can always check out Good First Issues. These are some issues that we think would offer an easier entry into Iris, so have a look and see if there's anything you'd like to have a crack at!
| @@ -4,37 +4,30 @@ | |||
| Loading Iris Cubes | |||
| =================== | |||
|
|
|||
| To load a single file into a **list** of Iris cubes | |||
| the :py:func:`iris.load` function is used:: | |||
| Start by loading a data file into our notebook. Supported file types include common meteorological formats such as ``.pp``, ``.nc``, and ``.grib2``. The :py:func:`iris.load` function returns a :class:`iris.cube.CubeList` object, which is essentially a list of :class:`iris.cube.Cube` objects. | |||
There was a problem hiding this comment.
Start by loading a data file into our notebook.
This is a bit misleading, iris can be used in notebooks, but also just in any editor that supports python.
Supported file types include common meteorological formats such as ``.pp``, ``.nc``, and ``.grib2``.
What was your motivation in removing this from a note? Personally, it feels a bit of a tangential point, which tends to suit "note" functionality.
The :py:func:``iris.load`` function returns a :class:``iris.cube.CubeList`` object, which is essentially a list of :class:``iris.cube.Cube`` objects.
Again, what was your motivation in removing this from a note? This also feels a bit tangential point, so I would leave this as a note.
| import iris | ||
| filename = '/path/to/file' | ||
| cubes = iris.load(filename) |
There was a problem hiding this comment.
What was your motivation for removing this example?
| Iris will attempt to return **as few cubes as possible** | ||
| by collecting together multiple fields with a shared standard name | ||
| into a single multidimensional cube. |
There was a problem hiding this comment.
This seems directly relevant to the example below, what were your reasons behind moving this?
| Iris will attempt to return **as few cubes as possible** | ||
| by collecting together multiple fields with a shared standard name | ||
| into a single multidimensional cube. |
There was a problem hiding this comment.
Adding this before comments of the example confuses this a bit, in my opinion. It'd be better to have all mentions of the example as soon after said example as possible.
|
|
||
| The output shows that there were 2 cubes as a result of loading the file, they were: |
There was a problem hiding this comment.
This change is only really necessary if there is extra discussion between this and the example, which I would be against.
| >>>file_path = '/path/to/file/uk_hires.pp' | ||
| >>>uk_hires_cubes = iris.load(file_path) | ||
| >>>print(uk_hires_cubes) |
There was a problem hiding this comment.
This code doesn't work, whereas the original code is fully functional.
| >>>print(uk_hires_cubes[1:]) | ||
| 0: surface_altitude / (m) (grid_latitude: 204; grid_longitude: 187) |
There was a problem hiding this comment.
Although this is accurate, I'm not sure what additional value it adds
| Currently there is support for CF NetCDF, GRIB 1 & 2, PP and FieldsFiles | ||
| file formats with a framework for this to be extended to custom formats. |
There was a problem hiding this comment.
What made you decide to move this?
|
|
||
| In order to find out what has been loaded, the result can be printed: | ||
| An example of using the :py:func:`iris.load` function:: |
There was a problem hiding this comment.
The example below is not just iris.load, but also of printing the cube list.
| @@ -4,37 +4,30 @@ | |||
| Loading Iris Cubes | |||
There was a problem hiding this comment.
A couple of things to note, across the whole pull request.
- Super long sentences all on one line can be hard to read; IDEs often don't wrap these. However, with .rst, continuing a sentence across multiple lines doesn't change how it's rendered, but does make it easier to read from IDEs. As such, we tend to limit lines to 80 characters, and split anything longer over multiple lines.
- Adding a space after
>>>makes it easier to read, i.e.>>> print('hello')is better than>>>print('hello'). - We tend to lean away from the imperative. Examples offer particular uses of functions etc., so rather than saying
"do this ...", we'll say"to do this, ...". It's a subtle change, but it does make a difference to how it's understood.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #6232 +/- ##
=======================================
Coverage 89.83% 89.83%
=======================================
Files 88 88
Lines 23315 23315
Branches 4338 4338
=======================================
Hits 20945 20945
Misses 1644 1644
Partials 726 726 ☔ View full report in Codecov by Sentry. |
|
Hi @Qinqing-Li, I'm closing this issue as there doesn't seem to be any movement on it. |
🚀 Pull Request
Description
iris.load()functionConsult Iris pull request check list