Merge pull request #1164 from hamza-mobeen/docs/co2-signal-token-403

docs: explain electricitymaps_api_token and query behaviour

Author: benoit-cty

docs/how-to/configuration.md

@@ -84,6 +84,44 @@ Yields attributes:
     which relies on the [INI
     syntax](https://docs.python.org/3/library/configparser.html#supported-ini-file-structure).
 
+## Electricity Maps API Token
+
+By default, CodeCarbon estimates carbon intensity using annual country-level
+averages from Our World in Data. Providing an `electricitymaps_api_token`
+upgrades this to **real-time carbon intensity** data from the
+[Electricity Maps API](https://api.electricitymaps.com), giving more accurate
+emissions figures — especially useful if your grid's energy mix varies
+throughout the day.
+
+**Without a token:** CodeCarbon uses a static annual average for your country.
+
+**With a token:** CodeCarbon queries the Electricity Maps API for the current
+carbon intensity of your grid. The query runs at the end of each tracking run,
+and also periodically during long runs (every
+`api_call_interval × measure_power_secs` seconds; default: every ~2 minutes).
+
+The Electricity Maps API offers a free tier. You can sign up and get a token at
+[electricitymaps.com](https://app.electricitymaps.com/sign-up).
+
+Set it in your config file:
+
+``` ini
+[codecarbon]
+electricitymaps_api_token = your-token-here
+```
+
+Or in code:
+
+``` python
+EmissionsTracker(electricitymaps_api_token="your-token-here")
+```
+
+!!! note "Deprecated parameter"
+
+    The old parameter name `co2_signal_api_token` still works for backward
+    compatibility but is deprecated and will be removed in a future version.
+    Use `electricitymaps_api_token` instead.
+
 ## Access internet through proxy server
 
 If you need a proxy to access internet, which is needed to call a Web