Add documentation on putting text onto images

doc/source/index.rst

@@ -63,12 +63,12 @@ Documentation
     data_download
     examples/index
     quickstart
-    readers
+    reading
     remote_reading
     composites
     resample
     enhancements
-    writers
+    writing
     multiscene
     dev_guide/index
 

doc/source/overview.rst

@@ -127,7 +127,7 @@ Reading
 
 One of the biggest advantages of using Satpy is the large number of input
 file formats that it can read. It encapsulates this functionality into
-individual :doc:`readers`. Satpy Readers handle all of the complexity of
+individual :doc:`reading`. Satpy Readers handle all of the complexity of
 reading whatever format they represent. Meteorological Satellite file formats
 can be extremely complex and formats are rarely reused across satellites
 or instruments. No matter the format, Satpy's Reader interface is meant to
@@ -174,7 +174,7 @@ should look. Satpy tries to hide the complexity of all the possible
 enhancement methods from the user and just provide the best looking image
 by default. Satpy still makes it possible to customize these procedures, but
 in most cases it shouldn't be necessary. See the documentation on
-:doc:`writers` for more information on what's possible for output formats
+:doc:`writing` for more information on what's possible for output formats
 and enhancing images.
 
 Writing
@@ -187,4 +187,4 @@ users to save data in image formats like PNG or GeoTIFF as well as data file
 formats like NetCDF. Each format's complexity is hidden behind the interface
 of individual Writer objects and includes keyword arguments for accessing
 specific format features like compression and output data type. See the
-:doc:`writers` documentation for the available writers and how to use them.
+:doc:`writing` documentation for the available writers and how to use them.

doc/source/quickstart.rst

@@ -122,7 +122,7 @@ To access the loaded data use the wavelength or name:
     >>> print(global_scene[0.8])
 
 For more information on loading datasets by resolution, calibration, or other
-advanced loading methods see the :doc:`readers` documentation.
+advanced loading methods see the :doc:`reading` documentation.
 
 
 Calculating measurement values and navigation coordinates
@@ -255,7 +255,7 @@ Or to save an individual dataset:
 Datasets are automatically scaled or "enhanced" to be compatible with the
 output format and to provide the best looking image. For more information
 on saving datasets and customizing enhancements see the documentation on
-:doc:`writers`.
+:doc:`writing`.
 
 
 Slicing and subsetting scenes

doc/source/readers.rst → doc/source/reading.rst

@@ -1,16 +1,16 @@
 =======
-Readers
+Reading
 =======
 
 .. todo::
 
     How to read cloud products from NWCSAF software. (separate document?)
 
 Satpy supports reading and loading data from many input file formats and
-schemes. The :class:`~satpy.scene.Scene` object provides a simple interface
-around all the complexity of these various formats through its ``load``
-method. The following sections describe the different way data can be loaded,
-requested, or added to a Scene object.
+schemes through the concept of *readers*. Each reader supports a specific type of input data.
+The :class:`~satpy.scene.Scene` object provides a simple interface around all the complexity of
+these various formats through its ``load`` method.
+The following sections describe the different way data can be loaded, requested, or added to a Scene object.
 
 Available Readers
 =================
@@ -116,7 +116,7 @@ Starting with Satpy version 0.25.1 with supported readers it is possible to
 load data from remote file systems like ``s3fs`` or ``fsspec``.
 For example:
 
-::
+.. code-block:: python
 
     >>> from satpy import Scene
     >>> from satpy.readers import FSFile

doc/source/writers.rst → doc/source/writing.rst

@@ -1,26 +1,26 @@
 =======
-Writers
+Writing
 =======
 
-Satpy makes it possible to save datasets in multiple formats. For details
-on additional arguments and features available for a specific Writer see
-the table below. Most use cases will want to save datasets using the
+Satpy makes it possible to save datasets in multiple formats, with *writers* designed to save in a given format.
+For details on additional arguments and features available for a specific Writer see the table below.
+Most use cases will want to save datasets using the
 :meth:`~satpy.scene.Scene.save_datasets` method::
 
-    >>> scn.save_datasets(writer='simple_image')
+    >>> scn.save_datasets(writer="simple_image")
 
 The ``writer`` parameter defaults to using the ``geotiff`` writer.
 One common parameter across almost all Writers is ``filename`` and
 ``base_dir`` to help automate saving files with custom filenames::
 
     >>> scn.save_datasets(
-    ...     filename='{name}_{start_time:%Y%m%d_%H%M%S}.tif',
-    ...     base_dir='/tmp/my_ouput_dir')
+    ...     filename="{name}_{start_time:%Y%m%d_%H%M%S}.tif",
+    ...     base_dir="/tmp/my_ouput_dir")
 
 .. versionchanged:: 0.10
 
     The `file_pattern` keyword argument was renamed to `filename` to match
-    the `save_dataset` method's keyword argument.
+    the `save_dataset` method"s keyword argument.
 
 .. _writer_table:
 
@@ -129,10 +129,40 @@ and save them all at once.
 
     >>> from satpy.writers import compute_writer_results
     >>> res1 = scn.save_datasets(filename="/tmp/{name}.png",
-    ...                          writer='simple_image',
+    ...                          writer="simple_image",
     ...                          compute=False)
     >>> res2 = scn.save_datasets(filename="/tmp/{name}.tif",
-    ...                          writer='geotiff',
+    ...                          writer="geotiff",
     ...                          compute=False)
     >>> results = [res1, res2]
     >>> compute_writer_results(results)
+
+
+Adding text to images
+=====================
+
+Satpy, via :doc:`pydecorate <pydecorate:index>`, can add text to images when they're being saved.
+To use this functionality, you must create a dictionary describing the text
+to be added.
+
+.. code-block:: python
+
+    >>> decodict = {"decorate": [{"text": {"txt": "my_text",
+    ...                                    "align": {"top_bottom": "top", "left_right": "left"},
+    ...                                    "font": <path_to_font>,
+    ...                                    "font_size": 48,
+    ...                                    "line": "white",
+    ...                                    "bg_opacity": 255,
+    ...                                    "bg": "black",
+    ...                                    "height": 30,
+    ...                                     }}]}
+
+Where `my_text` is the text you wish to add and `<path_to_font>` is the
+location of the font file you wish to use, often in `/usr/share/fonts/`
+
+This dictionary can then be passed to the :meth:`~satpy.scene.Scene.save_dataset` or :meth:`~satpy.scene.Scene.save_datasets` command.
+
+.. code-block:: python
+
+    >>> scene.save_dataset(my_dataset, writer="simple_image", fill_value=False,
+    ...                    decorate=decodict)

satpy/dataset/dataid.py

@@ -253,6 +253,7 @@
                                   'reflectance',
                                   'brightness_temperature',
                                   'radiance',
+                                  'radiance_wavenumber',
                                   'counts'
                                   ],
                               'transitive': True,
@@ -700,7 +701,7 @@
                 distance = np.inf
             elif isinstance(dataid_val, numbers.Number):
                 # so as to get the highest resolution first
                 # FIXME: this ought to be clarified, not sure that
                 # higher resolution is preferable is all cases.
                 # Moreover this might break with other numerical
                 # values.

satpy/readers/modis_l2.py

@@ -28,7 +28,7 @@
     - m[o/y]d35_l2: cloud_mask dataset
     - some datasets in m[o/y]d06 files
 
-To get a list of the available datasets for a given file refer to the "Load data" section in :doc:`../readers`.
+To get a list of the available datasets for a given file refer to the "Load data" section in :doc:`../reading`.
 
 
 Geolocation files

satpy/readers/seviri_base.py

@@ -139,7 +139,7 @@
 
 * The ``orbital_parameters`` attribute provides the nominal and actual satellite
   position, as well as the projection centre. See the `Metadata` section in
-  the :doc:`../readers` chapter for more information.
+  the :doc:`../reading` chapter for more information.
 
 * The ``acq_time`` coordinate provides the mean acquisition time for each
   scanline. Use a ``MultiIndex`` to enable selection by acquisition time:

satpy/scene.py

@@ -1195,7 +1195,7 @@ def save_dataset(self, dataset_id, filename=None, writer=None,
                 :doc:`dask:delayed` object or two lists to be passed to
                 a `dask.array.store` call. See return values below for more
                 details.
-            kwargs: Additional writer arguments. See :doc:`../writers` for more
+            kwargs: Additional writer arguments. See :doc:`../writing` for more
                 information.
 
         Returns:
@@ -1249,7 +1249,7 @@ def save_datasets(self, writer=None, filename=None, datasets=None, compute=True,
                 :doc:`dask:delayed` object or two lists to be passed to
                 a `dask.array.store` call. See return values below for more
                 details.
-            kwargs: Additional writer arguments. See :doc:`../writers` for more
+            kwargs: Additional writer arguments. See :doc:`../writing` for more
                 information.
 
         Returns: