chore: improve doc generation and test (#762)

Improve documentation generation and add tests for documentation.
Extend sphinx by todo directive.

The configuration table is now split into several tables. The test
is adapted accordingly.

There is a new test that checks the docstrings to be compliant to the
RST format as used by sphinx to create the documentation. We can not
use Markdown in docstrings. The docstrings are adapted accordingly.

An additional test checks that the documentation can be build with sphinx.
This test takes very long is only enabled in full run (aka. ci) mode.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

src/akkudoktoreos/prediction/predictionabc.py

@@ -70,20 +70,23 @@ class PredictionSequence(DataSequence):
         Derived classes have to provide their own records field with correct record type set.
 
     Usage:
-        # Example of creating, adding, and using PredictionSequence
-        class DerivedSequence(PredictionSquence):
-            records: List[DerivedPredictionRecord] = Field(default_factory=list, json_schema_extra={ "description": "List of prediction records" })
+        .. code-block:: python
 
-        seq = DerivedSequence()
-        seq.insert(DerivedPredictionRecord(date_time=datetime.now(), temperature=72))
-        seq.insert(DerivedPredictionRecord(date_time=datetime.now(), temperature=75))
+            # Example of creating, adding, and using PredictionSequence
+            class DerivedSequence(PredictionSquence):
+                records: List[DerivedPredictionRecord] = Field(default_factory=list, json_schema_extra={ "description": "List of prediction records" })
 
-        # Convert to JSON and back
-        json_data = seq.to_json()
-        new_seq = DerivedSequence.from_json(json_data)
+            seq = DerivedSequence()
+            seq.insert(DerivedPredictionRecord(date_time=datetime.now(), temperature=72))
+            seq.insert(DerivedPredictionRecord(date_time=datetime.now(), temperature=75))
+
+            # Convert to JSON and back
+            json_data = seq.to_json()
+            new_seq = DerivedSequence.from_json(json_data)
+
+            # Convert to Pandas Series
+            series = seq.key_to_series('temperature')
 
-        # Convert to Pandas Series
-        series = seq.key_to_series('temperature')
     """
 
     # To be overloaded by derived classes.
@@ -224,9 +227,10 @@ class PredictionImportProvider(PredictionProvider, DataImportProvider):
     """Abstract base class for prediction providers that import prediction data.
 
     This class is designed to handle prediction data provided in the form of a key-value dictionary.
+
     - **Keys**: Represent identifiers from the record keys of a specific prediction.
     - **Values**: Are lists of prediction values starting at a specified `start_datetime`, where
-      each value corresponds to a subsequent time interval (e.g., hourly).
+        each value corresponds to a subsequent time interval (e.g., hourly).
 
     Subclasses must implement the logic for managing prediction data based on the imported records.
     """

src/akkudoktoreos/prediction/pvforecastakkudoktor.py

@@ -12,51 +12,53 @@ Classes:
     PVForecastAkkudoktor: Primary class to manage PV power forecasts, handle data retrieval, caching, and integration with Akkudoktor.net.
 
 Example:
-    # Set up the configuration with necessary fields for URL generation
-    settings_data = {
-        "general": {
-            "latitude": 52.52,
-            "longitude": 13.405,
-        },
-        "prediction": {
-            "hours": 48,
-            "historic_hours": 24,
-        },
-        "pvforecast": {
-            "provider": "PVForecastAkkudoktor",
-            "planes": [
-                {
-                    "peakpower": 5.0,
-                    "surface_azimuth": 170,
-                    "surface_tilt": 7,
-                    "userhorizon": [20, 27, 22, 20],
-                    "inverter_paco": 10000,
-                },
-                {
-                    "peakpower": 4.8,
-                    "surface_azimuth": 90,
-                    "surface_tilt": 7,
-                    "userhorizon": [30, 30, 30, 50],
-                    "inverter_paco": 10000,
-                }
-            ]
+    .. code-block:: python
+
+        # Set up the configuration with necessary fields for URL generation
+        settings_data = {
+            "general": {
+                "latitude": 52.52,
+                "longitude": 13.405,
+            },
+            "prediction": {
+                "hours": 48,
+                "historic_hours": 24,
+            },
+            "pvforecast": {
+                "provider": "PVForecastAkkudoktor",
+                "planes": [
+                    {
+                        "peakpower": 5.0,
+                        "surface_azimuth": 170,
+                        "surface_tilt": 7,
+                        "userhorizon": [20, 27, 22, 20],
+                        "inverter_paco": 10000,
+                    },
+                    {
+                        "peakpower": 4.8,
+                        "surface_azimuth": 90,
+                        "surface_tilt": 7,
+                        "userhorizon": [30, 30, 30, 50],
+                        "inverter_paco": 10000,
+                    }
+                ]
+            }
         }
-    }
 
-    # Create the config instance from the provided data
-    config = PVForecastAkkudoktorSettings(**settings_data)
+        # Create the config instance from the provided data
+        config = PVForecastAkkudoktorSettings(**settings_data)
 
-    # Initialize the forecast object with the generated configuration
-    forecast = PVForecastAkkudoktor(settings=config)
+        # Initialize the forecast object with the generated configuration
+        forecast = PVForecastAkkudoktor(settings=config)
 
-    # Get an actual forecast
-    forecast.update_data()
+        # Get an actual forecast
+        forecast.update_data()
 
-    # Update the AC power measurement for a specific date and time
-    forecast.update_value(to_datetime(None, to_maxtime=False), "pvforecastakkudoktor_ac_power_measured", 1000.0)
+        # Update the AC power measurement for a specific date and time
+        forecast.update_value(to_datetime(None, to_maxtime=False), "pvforecastakkudoktor_ac_power_measured", 1000.0)
 
-    # Report the DC and AC power forecast along with AC measurements
-    print(forecast.report_ac_power_and_measurement())
+        # Report the DC and AC power forecast along with AC measurements
+        print(forecast.report_ac_power_and_measurement())
 
 Attributes:
     hours (int): Number of hours into the future to forecast. Default is 48.

src/akkudoktoreos/prediction/weatherclearoutside.py

@@ -117,17 +117,25 @@ class WeatherClearOutside(WeatherProvider):
 
         Workflow:
             1. **Retrieve Web Content**: Uses a helper method to fetch or retrieve cached ClearOutside HTML content.
+
             2. **Extract Forecast Date and Timezone**:
-                - Parses the forecast's start and end dates and the UTC offset from the "Generated" header.
+                - Parses the forecast's start and end dates and the UTC offset from the "Generated"
+                    header.
+
             3. **Extract Weather Data**:
                 - For each day in the 7-day forecast, the function finds detailed weather parameters
-                and associates values for each hour.
-                - Parameters include cloud cover, temperature, humidity, visibility, and precipitation type, among others.
+                    and associates values for each hour.
+                - Parameters include cloud cover, temperature, humidity, visibility, and
+                    precipitation type, among others.
+
             4. **Irradiance Calculation**:
-                - Calculates irradiance (GHI, DNI, DHI) values using cloud cover data and the `pvlib` library.
+                - Calculates irradiance (GHI, DNI, DHI) values using cloud cover data and the
+                    `pvlib` library.
+
             5. **Store Data**:
                 - Combines all hourly data into `WeatherDataRecord` objects, with keys
-                standardized according to `WeatherDataRecord` attributes.
+                    standardized according to `WeatherDataRecord` attributes.
+
         """
         # Get ClearOutside web content - either from site or cached
         response = self._request_forecast(force_update=force_update)  # type: ignore