Merge branch '317-add-tests-for-the-ogc-kml-22-conformance-test-suite…

…' into ogc_test_suit

docs/create_kml_files.rst

@@ -6,6 +6,14 @@ Read a shapefile and build a 3D KML visualization.
 
 This example shows how to read a shapefile and build a 3D KML visualization from it.
 
+.. image:: co2-per-capita-2020.jpg
+    :alt: CO2 emissions per capita in 2020
+    :align: center
+    :width: 800px
+    :target: https://ion.cesium.com/stories/viewer/?id=a3cf93bb-bbb8-488b-8643-09c037ec12b8
+
+(click on the image to see the KML visualization in Cesium Ion)
+
 You will need to install `pyshp <https://pypi.org/project/pyshp/>`_ (``pip install pyshp``).
 
 For this example we will use the
@@ -108,12 +116,6 @@ Finally, we create the KML object and write it to a file:
 
 The resulting KML file can be opened in Google Earth or any other KML viewer.
 
-.. image:: co2-per-capita-2020.jpg
-    :alt: CO2 emissions per capita in 2020
-    :align: center
-    :width: 800px
-    :target: https://ion.cesium.com/stories/viewer/?id=a3cf93bb-bbb8-488b-8643-09c037ec12b8
-
 
 Build an animated over time KML visualization
 ----------------------------------------------
@@ -122,6 +124,14 @@ This example shows how to build an animated KML visualization over time.
 We will use the same data as in the previous example, but this time we will
 create a KML file that shows the CO2 emissions accumulating from 1995 to 2022.
 
+.. image:: co2growth.gif
+    :alt: CO2 emissions per capita growth
+    :align: center
+    :width: 800px
+    :target: https://ion.cesium.com/stories/viewer/?id=602c8c64-72aa-4c57-8a01-752b6fbc62d0
+
+(click on the image to see the full visualization in Cesium Ion)
+
 First we import the necessary modules:
 
 .. code-block:: pycon

docs/fastkml.rst

@@ -43,6 +43,14 @@ fastkml.kml\_base
     :undoc-members:
     :show-inheritance:
 
+fastkml.helpers
+----------------------
+
+.. automodule:: fastkml.helpers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 fastkml.about
 --------------------
 
@@ -53,9 +61,6 @@ fastkml.about
 
    .. autodata:: __version__
 
-
-
-
 fastkml.atom
 -------------------
 
@@ -64,7 +69,6 @@ fastkml.atom
    :undoc-members:
    :show-inheritance:
 
-
 fastkml.config
 ---------------------
 
@@ -129,14 +133,6 @@ fastkml.gx
    :undoc-members:
    :show-inheritance:
 
-fastkml.helpers
-----------------------
-
-.. automodule:: fastkml.helpers
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 fastkml.kml
 ------------------
 

fastkml/enums.py

@@ -26,6 +26,22 @@
 from enum import Enum
 from enum import unique
 
+__all__ = [
+    "AltitudeMode",
+    "ColorMode",
+    "DataType",
+    "DateTimeResolution",
+    "DisplayMode",
+    "GridOrigin",
+    "PairKey",
+    "RefreshMode",
+    "RelaxedEnum",
+    "Shape",
+    "Units",
+    "Verbosity",
+    "ViewRefreshMode",
+]
+
 logger = logging.getLogger(__name__)
 
 
@@ -40,14 +56,15 @@ class RelaxedEnum(Enum):
     Usage:
         To use this enum, simply subclass `RelaxedEnum` and define your enum values.
 
-    Example:
-    -------
-        class MyEnum(RelaxedEnum):
-            VALUE1 = "value1"
-            VALUE2 = "value2"
+    Example::
+
+        class AltitudeMode(RelaxedEnum):
+            clamp_to_ground = "clampToGround"
+            relative_to_ground = "relativeToGround"
+            absolute = "absolute"
 
-        my_value = MyEnum("VALUE1")  # Case-insensitive match
-        print(my_value)  # Output: MyEnum.VALUE1
+        my_value = AltitudeMode("CLAMPTOGROUND")  # Case-insensitive match
+        print(my_value)  # Output: AltitudeMode.clamp_to_ground
 
     The subclass must define all values as strings.
 
@@ -102,33 +119,33 @@ class AltitudeMode(RelaxedEnum):
     Possible values are
 
     - clampToGround - (default) Indicates to ignore an altitude specification
-        (for example, in the <coordinates> tag).
+      (for example, in the <coordinates> tag).
     - relativeToGround - Sets the altitude of the element relative to the actual
-        ground elevation of a particular location.
-        For example, if the ground elevation of a location is exactly at sea level
-        and the altitude for a point is set to 9 meters,
-        then the elevation for the icon of a point placemark elevation is 9 meters
-        with this mode.
-        However, if the same coordinate is set over a location where the ground
-        elevation is 10 meters above sea level, then the elevation of the coordinate
-        is 19 meters.
-        A typical use of this mode is for placing telephone poles or a ski lift.
+      ground elevation of a particular location.
+      For example, if the ground elevation of a location is exactly at sea level
+      and the altitude for a point is set to 9 meters,
+      then the elevation for the icon of a point placemark elevation is 9 meters
+      with this mode.
+      However, if the same coordinate is set over a location where the ground
+      elevation is 10 meters above sea level, then the elevation of the coordinate
+      is 19 meters.
+      A typical use of this mode is for placing telephone poles or a ski lift.
     - absolute - Sets the altitude of the coordinate relative to sea level,
-        regardless of the actual elevation of the terrain beneath the element.
-        For example, if you set the altitude of a coordinate to 10 meters with an
-        absolute altitude mode, the icon of a point placemark will appear to be at
-        ground level if the terrain beneath is also 10 meters above sea level.
-        If the terrain is 3 meters above sea level, the placemark will appear elevated
-        above the terrain by 7 meters.
-        A typical use of this mode is for aircraft placement.
+      regardless of the actual elevation of the terrain beneath the element.
+      For example, if you set the altitude of a coordinate to 10 meters with an
+      absolute altitude mode, the icon of a point placemark will appear to be at
+      ground level if the terrain beneath is also 10 meters above sea level.
+      If the terrain is 3 meters above sea level, the placemark will appear elevated
+      above the terrain by 7 meters.
+      A typical use of this mode is for aircraft placement.
     - relativeToSeaFloor - Interprets the altitude as a value in meters above the
-        sea floor.
-        If the point is above land rather than sea, the altitude will be interpreted
-        as being above the ground.
+      sea floor.
+      If the point is above land rather than sea, the altitude will be interpreted
+      as being above the ground.
     - clampToSeaFloor - The altitude specification is ignored, and the point will be
-        positioned on the sea floor.
-        If the point is on land rather than at sea, the point will be positioned on
-        the ground.
+      positioned on the sea floor.
+      If the point is on land rather than at sea, the point will be positioned on
+      the ground.
 
     The Values relativeToSeaFloor and clampToSeaFloor are not part of the KML definition
     but of the  <gx:altitudeMode> a KML extension in the Google extension namespace,

fastkml/registry.py

@@ -20,6 +20,14 @@
 This approach allows for flexible, declarative mapping between XML and Python objects,
 with the registry acting as a central configuration for these mappings.
 
+Direct ``Registry`` class use is typically only for library internals or advanced
+customization. For normal usage, stick with the ``registry`` instance:
+
+- The library is designed around this global instance.
+- Ensures all parts of the library use the same registry.
+- Pre-populated with standard KML mappings.
+- Singleton pattern: Avoids multiple conflicting registries.
+
 """
 
 from dataclasses import dataclass
@@ -116,14 +124,6 @@ class Registry:
     - Enable consistent handling of attributes across different KML classes.
     - Facilitate extensibility and maintainability of the library.
 
-    Direct ``Registry`` class use is typically only for library internals or advanced
-    customization. For normal usage, stick with the ``registry`` instance:
-
-    - The library is designed around this global instance.
-    - Ensures all parts of the library use the same registry.
-    - Pre-populated with standard KML mappings.
-    - Singleton pattern: Avoids multiple conflicting registries.
-
     """
 
     _registry: Dict[Type["_XMLObject"], List[RegistryItem]]