doc for data api done

Author: shubhvjain

codegreen_core/data/__init__.py

@@ -1,3 +1,5 @@
 from .main import *
+from .offline import * 
+# from . import main 
 
-__all__ = ["energy","info"]
+__all__ = ["info","energy","sync_offline_data",'get_offline_data']

codegreen_core/data/offline.py

@@ -243,16 +243,27 @@ def _get_offline_cache_data(country,start,end):
         return False,None
 
 
-def get_offline_data(country,start,end,sync_first=False):
+def get_offline_data(country,start,end,sync_first=False)->dict:
     """
-    This method returns locally stored energy data. 
-    Data is stored in 2 sources : one. Redis cache and second : csv files. 
-    Redis cache contains data only for the last 72 hours from when it was last synced
-    Offline data files can contain data for longer durations.
-    Both these options can be configured in the config file
-    returns {available:True/False, data:dataframe}
-    Note that this method assumes that syncing of the sources is being handled separately  
+    This method returns locally stored energy data.
+
+    Data is stored in two sources:
+
+    1. **Redis cache**: Contains data for a limited number of hours from the last sync.
+    2. **CSV files**: Contain data for longer durations.
+
+    Both storage options can be configured in the configuration file.
+
+    **Note**: Unless you specify the ``sync_first`` flag, the method assumes that syncing of the data sources is handled separately. If ``sync_first`` is set to ``True`` and data files are not initialized in advance, the method may take longer to complete
+
+    :return: A dictionary with the following keys:
+        - **available** (*bool*): Indicates if the data is available.
+        - **data** (*pandas.DataFrame*): The energy data, if available. Otherwise, an empty DataFrame.
+
+    :rtype: dict
+
     """
+
     output = {"available":False,"data":None, "partial":False,"source":""}
     offline = Config.get("enable_offline_energy_generation")
     cache =  Config.get("enable_energy_caching")
@@ -264,7 +275,7 @@ def get_offline_data(country,start,end,sync_first=False):
     if cache :
         # first look in the cache
         if(sync_first):
-            print("will first sync the cache to get the latest data")
+            #print("will first sync the cache to get the latest data")
             _sync_offline_cache(country)
         partial,data = _get_offline_cache_data(country,start,end)   
         if data is not None and partial is False:
@@ -278,37 +289,39 @@ def get_offline_data(country,start,end,sync_first=False):
     if offline:
         # first look if data files are available, if yes, return data 
         if(sync_first):
-            print("will first sync the offline files to get the latest data")
+            #print("will first sync the offline files to get the latest data")
             _sync_offline_file(country)
         partial,data = _get_offline_file_data(country,start,end)
         output["partial"] = partial
         output["data"] = data
         output["available"] = True
         output["source"] = "offline_file"
-        print("just got the data from offline file")
+        #print("just got the data from offline file")
 
     return output
 
 
 def sync_offline_data(file=False,cache=False):
     """
-    This method syncs offline data for offline sources enabled in the cache. 
-    Data is synced for all available countries 
-    You need to run this before getting offline data. you can even setup a CRON job to call this method on regular intervals
+    This method syncs offline data for offline sources enabled in the configuration file. The data is synced for all available countries. 
+    
+    You need to run this method before retrieving offline data. It is also possible to set up a CRON job to call this method at regular intervals to keep data synchronized.
+    
+    The sync operation can take some time, depending on the data size and the selected sync options (file, cache, or both).
+
+    :param bool file: If ``True``, sync data in offline files. Defaults to ``False``.
+    :param bool cache: If ``True``, sync data in the cache. Defaults to ``False``.
     """
     c_keys = meta.get_country_metadata()
     if  Config.get("enable_offline_energy_generation") == True  and file == True:
         for key in c_keys:
             try:
                 _sync_offline_file(key)
             except Exception as e:
-                # print(e)
                 log_stuff("Error in syncing offline file for "+key+". Message"+ str(e))
     if  Config.get("enable_energy_caching") == True and cache == True :
         for key in c_keys:
             try:
                 _sync_offline_cache(key)
             except Exception as e:
-                # print(e)
                 log_stuff("Error in syncing offline file for "+key+". Message: "+ str(e))
-

codegreen_core/tools/loadshift_time.py

@@ -70,6 +70,31 @@ def predict_now(
     :type criteria: str
     :return: Tuple[timestamp, message, average_percent_renewable]
     :rtype: tuple
+
+    **Example usage**:
+
+    .. code-block:: python
+    
+        from datetime import datetime,timedelta 
+        from codegreen_core.tools.loadshift_time import predict_now
+
+        country_code = "DK"
+        est_runtime_hour = 10
+        est_runtime_min = 0
+        now = datetime.now()
+        hard_finish_date = now + timedelta(days=1)
+        criteria = "percent_renewable"
+        per_renewable = 50 
+
+        time = predict_now(country_code,
+                            est_runtime_hour,
+                            est_runtime_min,
+                            hard_finish_date,
+                            criteria,
+                            per_renewable)
+        # (1728640800.0, <Message.OPTIMAL_TIME: 'OPTIMAL_TIME'>, 76.9090909090909)
+    
+
     """
     if criteria == "percent_renewable":
         try:

docs/_static/modules.png

@@ -1,57 +1,9 @@
 codegreen_core API
 ===================
 
-
-Package Organization
----------------------
-
-.. image:: _static/modules.png
-   :alt: modules
-   :width: 400px  
-   :align: center 
-
-
-The package is divided into two main sub packages: `data`` and `tools`. (There is also an additional module, `utilities`, which provides helper methods that support other modules.)
-
-The `data` sub package contains methods for fetching energy production data. This package relies on external data sources to retrieve this information, which is then processed to make it usable by other components of the package. For more details and a complete API , see the data module documentation.
-
-The `tools` sub package provides a variety of tools, including:
-
-- Carbon intensity calculator
-- Carbon emission calculator
-- Optimal time-shifting predictor
-- Optimal location-shifting predictor
-
-
-Example : Calculating optimal time for a computational task 
--------------------------------------------------------------
-Assuming all the above steps are done, you can now calculate the optimal starting time for a computations. 
-
-.. code-block:: python
-  
-  from datetime import datetime,timedelta 
-  from codegreen_core.tools.loadshift_time import predict_now
-
-  country_code = "DK"
-  est_runtime_hour = 10
-  est_runtime_min = 0
-  now = datetime.now()
-  hard_finish_date = now + timedelta(days=1)
-  criteria = "percent_renewable"
-  per_renewable = 50 
-
-  time = predict_now(country_code,
-                    est_runtime_hour,
-                    est_runtime_min,
-                    hard_finish_date,
-                    criteria,
-                    per_renewable)
-  # (1728640800.0, <Message.OPTIMAL_TIME: 'OPTIMAL_TIME'>, 76.9090909090909)
-  
-
-
 The core package contains 2 main module :  
-- `data` : To fetch energy data for a country
+
+- `data` : To fetch energy data for a country.
 - `tools` : To calculate various quantities like Optimal computation time, carbon intensity etc. 
 
 

docs/api.rst

@@ -47,5 +47,9 @@
 html_theme = "alabaster"
 html_static_path = ["_static"]
 
+html_theme_options = {
+    "github_user": "codegreen-framework",
+    "github_repo": "codegreen-core"
+}
 
 # import codegreen_core

docs/conf.py

@@ -6,7 +6,7 @@ Here we describe how we calcualte stuff
 
 
 ``tools`` Module
-=================
+------------------
 
 This subpackage  provides tools and methods for tasks like calculating the carbon intensity of energy production and calculating the emissions produced due to a computation.