SSD1325 documentation update for grayscale support (#596)

* SSD1325 documentation update for grayscale

* Updated for use of Color

* Copy fixes, added example

changelog/v1.15.0.rst

@@ -82,6 +82,7 @@ Notable Changes & New Features
 - New Thermostat Controller implements ESPHome actions for all available Home Assistant climate actions,
   climate modes, fan modes, and fan swing modes (#1061)
 - Color (and grayscale) display support! (#1050)
+- SSD1325 component updated to facilitate use of grayscale
 
 All changes
 -----------

components/display/ssd1325.rst

@@ -22,7 +22,11 @@ displays with ESPHome. Note that this component is for displays that are connect
     SSD1325 OLED Display
 
 Connect CLK, DIN, CS, DC, and RST to pins on your ESP. For power, connect
-VCC to 3.3V and GND to GND.
+VCC to 3.3V and GND to GND. Note that two jumper resistors on the back of the
+display PCB may need to be moved to put the display into SPI mode.
+`Adafruit <https://www.adafruit.com/product/2674>`__ has a
+`guide <https://learn.adafruit.com/2-7-monochrome-128x64-oled-display-module/assembly>`__
+that explains how to do this, if necessary.
 
 .. code-block:: yaml
 
@@ -40,8 +44,8 @@ VCC to 3.3V and GND to GND.
         lambda: |-
           it.print(0, 0, id(font), "Hello World!");
 
-Configuration variables:
-************************
+Configuration Variables
+***********************
 
 - **model** (**Required**): The model of the display. Options are:
 
@@ -49,6 +53,7 @@ Configuration variables:
   - ``SSD1325 128x64``
   - ``SSD1325 96x16``
   - ``SSD1325 64x48``
+  - ``SSD1327 128x128`` **# Note the number seven!**
 
 - **reset_pin** (:ref:`Pin Schema <config-pin_schema>`): The RESET pin.
 - **cs_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin on the ESP that that the CS line is connected to.
@@ -60,6 +65,83 @@ Configuration variables:
 - **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 
+Configuration examples
+**********************
+
+To utilize the grayscale capabilities of this display module, add a ``color:`` section to your YAML configuration;
+please see :ref:`color <config-color>` for more details. As this is a grayscale display, it only uses the white color
+element as shown below.
+
+To use grayscale in your lambada:
+
+.. code-block:: yaml
+
+    color:
+      - id: medium_gray
+        white: 50%
+
+    ...
+
+    display:
+        ...
+        lambda: |-
+          it.rectangle(0,  0, it.get_width(), it.get_height(), id(medium_gray));
+
+
+To bring in grayscale images:
+
+.. code-block:: yaml
+
+    image:
+      - file: "image.jpg"
+        id: my_image
+        resize: 120x120
+        type: GRAYSCALE
+
+    ...
+
+    display:
+        ...
+        lambda: |-
+          it.image(0, 0, id(my_image));
+
+In this case, the image will be converted to grayscale (regardless of its original format) and rendered as such
+when drawn on the display. Note that the original image may require some adjustment as not all images immediately
+convert nicely to the 4-bit grayscale format this display supports.
+
+Note that if ``type: GRAYSCALE`` is omitted, the image will render as a binary image (no grayscale); in this
+case, a color attribute may be passed to the ``image()`` method as follows:
+
+.. code-block:: yaml
+
+    image:
+      - file: "image.jpg"
+        id: my_image
+        resize: 120x120
+
+    ...
+
+    display:
+        ...
+        lambda: |-
+          it.image(0, 0, id(medium_gray), id(my_image));
+
+This will draw the complete image with the given shade of gray.
+
+To create a new color as needed in code:
+
+.. code-block:: yaml
+
+    display:
+        ...
+        lambda: |-
+          float white_intensity = 0.5;
+          Color variable_gray(0, 0, 0, white_intensity);
+          it.rectangle(0,  0, it.get_width(), it.get_height(), variable_gray);
+
+The last argument of the ``Color`` constructor is the intensity of the white element; it is a percentage
+(value of range 0 to 1). It may be defined by another variable so it is adjustable in code.
+
 See Also
 --------