Add documentation on putting text onto images

[simonrp84]

As discussed on slack, this PR adds a brief example to the documentation to describe how text can be added to an image when using save_dataset.

[codecov]

Codecov Report

Merging #2517 (9286e4d) into main (93bae5e) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main    #2517   +/-   ##
=======================================
  Coverage   94.94%   94.94%           
=======================================
  Files         354      354           
  Lines       51474    51474           
=======================================
  Hits        48873    48873           
  Misses       2601     2601           

Flag	Coverage Δ
behaviourtests	4.27% <ø> (ø)
unittests	95.56% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
satpy/dataset/dataid.py	95.39% <ø> (ø)
satpy/readers/modis_l2.py	89.90% <ø> (ø)
satpy/readers/seviri_base.py	100.00% <ø> (ø)
satpy/scene.py	93.59% <ø> (ø)

[coveralls]

Pull Request Test Coverage Report for Build 5343898810

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 95.421%

---

Totals
Change from base Build 5338770761:	0.0%
Covered Lines:	47201
Relevant Lines:	49466

---

💛 - Coveralls

[gerritholl]

Should we change the name writers? The section is not only about writers, but about writing/saving images/products.

[djhoese]

Should we change the name writers? The section is not only about writers, but about writing/saving images/products.

This is difficult to answer. The confusion of the documentation page is mostly due to the poorly designed interfaces. That is, that you add overlays at save/write time rather than as a separate step. I don't think it is completely wrong where it is, but yeah maybe a name change to Writing would help?

[mraspaud]

Should we change the name writers? The section is not only about writers, but about writing/saving images/products.

This is difficult to answer. The confusion of the documentation page is mostly due to the poorly designed interfaces. That is, that you add overlays at save/write time rather than as a separate step. I don't think it is completely wrong where it is, but yeah maybe a name change to Writing would help?

I think Writing is a good name. @gerritholl any comments?

[mraspaud]

@simonrp84 not much left to finalise this one, want to give it a shot?

[djhoese]

Looks pretty good. You'll need to update the references to the reading and writing files in the index.rst file that points to them.

I made an inline comment for some changes. Additionally, do we want to go down the road of also documenting how to add coastlines? I suppose that would be easier when pycoast gets rewritten to automatically download/cache coastline shapefiles (a long term dream of mine), but that could be a while.

[djhoese]

Can we make this a simple string to not confuse people? Just "txt": "my text"?

And...based on the conversation at the meeting yesterday and @mraspaud's PR on the ruff linting tool, can we use double quotes for all of these strings please?

[simonrp84]

Done!

[simonrp84]

In general I like the idea of adding documentation on coastlines (I always end up having to search github issues for it). But I'm not sure we should add it in this PR, as I don't really have any time to work on it and we'd end up delaying the PR.

Will address your inline comment this evening.

[mraspaud]

I see also that the rtd build is failing, but I can't see what cause the error...

[djhoese]

@mraspaud In my comment above:

You'll need to update the references to the reading and writing files in the index.rst file that points to them.

[mraspaud]

@simonrp84 the rtd build is still failing...

[djhoese]

The remaining RTD errors are about docstrings referring to the old readers/writers.rst documents. Those fixes are left as an exercise for the reader.

[simonrp84]

Ok, RTD seems to work now but was getting a failing test - I think due to numpy 2.0. Have merged main and hopefully that will fix it...

[mraspaud]

@simonrp84 great job! the unstable build is still expected to fail so I'm merging this!

[simonrp84]

Thanks!