docs: restructure documentation using Diataxis framework

.github/workflows/test-package.yml

@@ -6,16 +6,11 @@ on:
   pull_request:
     paths:
       - "codecarbon/**"
-      - "test/**"
+      - "tests/**"
       - "pyproject.toml"
       - "uv.lock"
   push:
     branches: [master]
-    paths:
-      - "codecarbon/**"
-      - "test/**"
-      - "pyproject.toml"
-      - "uv.lock"
 
 jobs:
   python-test:

CONTRIBUTING.md

@@ -258,7 +258,7 @@ flake8...................................................................Passed
 
 If any of the linters/formatters fail, check the difference with `git diff`, add the differences if there is no behavior changes (isort and black might have change some coding style or import order, this is expected it is their job) with `git add` and finally try to commit again `git commit ...`.
 
-You can also run `pre-commit` with `uv run pre-commit run -v` if you have some changes staged but you are not ready yet to commit.
+You can also run `pre-commit` with `uv run pre-commit run --all-files` if you have some changes staged but you are not ready yet to commit.
 
 
 <!-- TOC --><a name="dependencies-management"></a>
@@ -363,6 +363,18 @@ cp /data/tests/test_package_integrity.py .
 pytest test_package_integrity.py
 ```
 
+### Contribute to a fork branch
+
+When a user open a PR from a fork, we are allowed to push to the fork branch.
+
+If you want to do so, do the following:
+
+```bash
+git remote add <user_name> https://github.com/<user_name>/codecarbon.git
+git fetch <user_name> <git_branch>
+git checkout -b <git_branch> <user_name>/<git_branch>
+```
+
 <!-- TOC --><a name="api-and-dashboard"></a>
 ## API and Dashboard
 

README.md

@@ -1,167 +1,129 @@
 ![banner](docs/images/banner.png)
 
-Estimate and track carbon emissions from your computer, quantify and analyze their impact.
-
-CodeCarbon websites:
-- [Main website](https://codecarbon.io) to learn why we do this.
-- [Dashboard](https://dashboard.codecarbon.io/) to see your emissions, [read the API doc](https://mlco2.github.io/codecarbon/api.html) before.
-- [Documentation](https://mlco2.github.io/codecarbon) to learn how to use the package and our methodology.
-- [GitHub](https://github.com/mlco2/codecarbon) to look at the source code and contribute.
-- [Discord](https://discord.gg/GS9js2XkJR) to chat with us.
-
-<!--  ![Discord Shield](https://discord.com/api/guilds/1090365182909350019/widget.png?style=shield) -->
+# Track & reduce CO₂ emissions from your local computing
 
-<br/>
-
-[![](https://img.shields.io/pypi/v/codecarbon?color=024758)](https://pypi.org/project/codecarbon/)
-[![DOI](https://zenodo.org/badge/263364731.svg)](https://zenodo.org/badge/latestdoi/263364731)
-<!-- [![Downloads](https://static.pepy.tech/badge/codecarbon/month)](https://pepy.tech/project/codecarbon) -->
-[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/mlco2/codecarbon/badge)](https://scorecard.dev/viewer/?uri=github.com/mlco2/codecarbon)
-[![codecov](https://codecov.io/gh/mlco2/codecarbon/graph/badge.svg)](https://codecov.io/gh/mlco2/codecarbon)
+Estimate and track carbon emissions from your computer, quantify and analyze their impact.
 
+[![](https://img.shields.io/pypi/v/codecarbon?color=024758)](https://pypi.org/project/codecarbon/) [![DOI](https://zenodo.org/badge/263364731.svg)](https://zenodo.org/badge/latestdoi/263364731) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/mlco2/codecarbon/badge)](https://scorecard.dev/viewer/?uri=github.com/mlco2/codecarbon) [![codecov](https://codecov.io/gh/mlco2/codecarbon/graph/badge.svg)](https://codecov.io/gh/mlco2/codecarbon)
 
-- [About CodeCarbon 💡](#about-codecarbon-)
-- [Quickstart 🚀](#quickstart-)
-  - [Installation 🔧](#installation-)
-  - [Start to estimate your impact 📏](#start-to-estimate-your-impact-)
-    - [Without using the online dashboard](#without-using-the-online-dashboard)
-    - [With the online dashboard](#with-the-online-dashboard)
-    - [Monitoring your machine 💻](#monitoring-your-machine-)
-    - [Detecting your hardware 🔍](#detecting-your-hardware-)
-    - [In your Python code 🐍](#in-your-python-code-)
-  - [Visualize 📊](#visualize-)
-- [Contributing 🤝](#contributing-)
-- [How To Cite 📝](#how-to-cite-)
-- [Contact 📝](#contact-)
-  - [Star History](#star-history)
+- **A lightweight, easy to use Python library** – Simple API to track emissions
+- **Open source, free & community driven** – Built by and for the community
+- **Effective visual outputs** – Put emissions in context with real-world equivalents
 
-# About CodeCarbon 💡
+> **Tracking GenAI API calls?** CodeCarbon measures emissions from **local computing** (your hardware). To track emissions from remote GenAI API calls (OpenAI, Anthropic, Mistral, etc.), use [**EcoLogits**](https://ecologits.ai/). Both tools are complementary.
 
-**CodeCarbon** started with a quite simple question:
+## Installation
 
-**What is the carbon emission impact of my computer program? :shrug:**
+```bash
+pip install codecarbon
+```
 
-We found some global data like "computing currently represents roughly 0.5% of the world’s energy consumption" but nothing on our individual/organisation level impact.
+If you use Conda:
 
-At **CodeCarbon**, we believe, along with Niels Bohr, that "Nothing exists until it is measured". So we found a way to estimate how much CO<sub>2</sub> we produce while running our code.
+```bash
+conda activate your_env
+pip install codecarbon
+```
 
-*How?*
+More installation options: [installation docs](https://docs.codecarbon.io/how-to/installation/).
 
-We created a Python package that estimates your hardware electricity power consumption (GPU + CPU + RAM) and we apply to it the carbon intensity of the region where the computing is done.
+## Quickstart (Python)
 
-![calculation Summary](docs/images/calculation.png)
+```python
+from codecarbon import EmissionsTracker
 
-We explain more about this calculation in the [**Methodology**](https://mlco2.github.io/codecarbon/methodology.html#) section of the documentation.
+tracker = EmissionsTracker()
+tracker.start()
 
-Our hope is that this package will be used widely for estimating the carbon footprint of computing, and for establishing best practices with regards to the disclosure and reduction of this footprint.
+# Your code here
 
-**So ready to "change the world one run at a time"? Let's start with a very quick set up.**
+emissions = tracker.stop()
+print(f"Emissions: {emissions} kg CO₂")
+```
 
-# Quickstart 🚀
+[**Learn more** →](https://docs.codecarbon.io/tutorials/first-tracking/)
 
-## Installation 🔧
+## Quickstart (CLI)
 
-**From PyPI repository**
-```python
-pip install codecarbon
-```
+Track a command without changing your code:
 
-**Using Conda environments**
-If you're using Conda, you can install CodeCarbon with pip in your Conda environment:
 ```bash
-conda activate your_env
-pip install codecarbon
+codecarbon monitor --no-api -- python train.py
 ```
 
-To see more installation options please refer to the documentation: [**Installation**](https://mlco2.github.io/codecarbon/installation.html#)
-
-## Start to estimate your impact 📏
+Detect your hardware:
 
-### Without using the online dashboard
-
-```python
-from codecarbon import track_emissions
-@track_emissions()
-def your_function_to_track():
-  # your code
+```bash
+codecarbon detect
 ```
 
-After running your code, you will find an `emissions.csv` that you can visualize with `carbonboard --filepath="examples/emissions.csv"`.
+Full CLI guide: [CLI tutorial](https://docs.codecarbon.io/tutorials/cli/).
 
-### With the online dashboard
+## Configuration
 
-To use the online dashboard you need to create an account on [**CodeCarbon Dashboard**](https://dashboard.codecarbon.io/).
-Once you have an account, you can create an experiment_id to track your emissions.
+You can configure CodeCarbon using:
 
-To get an experiment_id enter:
-```python
-! codecarbon login
-```
-You can now store it in a **.codecarbon.config** at the root of your project
-```python
-[codecarbon]
-log_level = DEBUG
-save_to_api = True
-experiment_id = 2bcbcbb8-850d-4692-af0d-76f6f36d79b2 #the experiment_id you get with init
-```
-Now you have 2 main options:
+- `~/.codecarbon.config` (global)
+- `./.codecarbon.config` (project-local)
+- `CODECARBON_*` environment variables
+- Python arguments (`EmissionsTracker(...)`)
 
-### Monitoring your machine 💻
+Configuration precedence and examples: [configuration guide](https://docs.codecarbon.io/how-to/configuration/).
 
-In your command prompt use:
-```codecarbon monitor```
-The package will track your emissions independently from your code.
+## How it works
 
-### Detecting your hardware 🔍
+We created a Python package that estimates your hardware electricity power consumption (GPU + CPU + RAM) and we apply to it the carbon intensity of the region where the computing is done.
 
-In your command prompt use:
-```codecarbon detect```
-The package will detect and print your hardware information (RAM, CPU, GPU).
+![calculation Summary](docs/images/calculation.png)
 
-### In your Python code 🐍
-```python
-from codecarbon import track_emissions
-@track_emissions()
-def your_function_to_track():
-  # your code
-  ```
-The package will track the emissions generated by the execution of your function.
+We explain more about this calculation in the [**Methodology**](https://docs.codecarbon.io/explanation/methodology/) section of the documentation.
 
-There is other ways to use **codecarbon** package, please refer to the documentation to learn more about it:  [**Usage**](https://mlco2.github.io/codecarbon/usage.html#)
+## Visualize
 
-## Visualize 📊
+You can visualize your experiment emissions on the [dashboard](https://dashboard.codecarbon.io/) or locally with [carbonboard](https://docs.codecarbon.io/how-to/visualize/).
 
-You can now visualize your experiment emissions on the [dashboard](https://dashboard.codecarbon.io/).
 ![dashboard](docs/images/dashboard.png)
 
+## Quick links
+
+| Section | Description |
+|---------|-------------|
+| [Quickstart](https://docs.codecarbon.io/tutorials/first-tracking/) | Get started in 5 minutes |
+| [Installation](https://docs.codecarbon.io/how-to/installation/) | Install CodeCarbon |
+| [CLI Tutorial](https://docs.codecarbon.io/tutorials/cli/) | Track emissions from the command line |
+| [Python API Tutorial](https://docs.codecarbon.io/tutorials/python-api/) | Track emissions in Python code |
+| [Comparing Model Efficiency](https://docs.codecarbon.io/tutorials/comparing-model-efficiency/) | Measure carbon efficiency across ML models |
+| [API Reference](https://docs.codecarbon.io/reference/api/) | Full parameter documentation |
+| [Examples](https://docs.codecarbon.io/reference/examples/) | Example usage patterns |
+| [Methodology](https://docs.codecarbon.io/explanation/methodology/) | How emissions are calculated |
+| [EcoLogits](https://ecologits.ai/) | Track emissions from GenAI API calls |
 
-> Hope you enjoy your first steps monitoring your carbon computing impact!
-> Thanks to the incredible codecarbon community 💪🏼 a lot more options are available using *codecarbon* including:
-> - offline mode
-> - cloud mode
-> - comet integration...
->
-> Please explore the [**Documentation**](https://mlco2.github.io/codecarbon) to learn about it
-> If ever what your are looking for is not yet implemented, let us know through the *issues* and even better become one of our 🦸🏼‍♀️🦸🏼‍♂️ contributors! more info 👇🏼
+## Links
 
+- [Main website](https://codecarbon.io) to learn why we do this.
+- [Dashboard](https://dashboard.codecarbon.io/) to see your emissions.
+- [Documentation](https://docs.codecarbon.io/) to learn how to use the package and our methodology.
+- [EcoLogits](https://ecologits.ai/) to track emissions from GenAI API calls (OpenAI, Anthropic, etc.).
+- [GitHub](https://github.com/mlco2/codecarbon) to look at the source code and contribute.
+- [Discord](https://discord.gg/GS9js2XkJR) to chat with us.
 
-# Contributing 🤝
+## Contributing
 
 We are hoping that the open-source community will help us edit the code and make it better!
 
-You are welcome to open issues, even suggest solutions and better still contribute the fix/improvement! We can guide you if you're not sure where to start but want to help us out 🥇
-
-In order to contribute a change to our code base, please submit a pull request (PR) via GitHub and someone from our team will go over it and accept it.
+You are welcome to open issues, even suggest solutions and better still contribute the fix/improvement! We can guide you if you're not sure where to start but want to help us out.
 
-Check out our [contribution guidelines :arrow_upper_right:](https://github.com/mlco2/codecarbon/blob/master/CONTRIBUTING.md)
+Check out our [contribution guidelines](https://github.com/mlco2/codecarbon/blob/master/CONTRIBUTING.md).
 
 Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
 
-# How To Cite 📝
+## Citation
 
 If you find CodeCarbon useful for your research, you can find a citation under a variety of formats on [Zenodo](https://zenodo.org/records/11171501).
 
-Here is a sample for BibTeX:
+<details>
+<summary>BibTeX</summary>
+
 ```tex
 @software{benoit_courty_2024_11171501,
   author       = {Benoit Courty and
@@ -189,7 +151,7 @@ Here is a sample for BibTeX:
                   Ziyao Wang and
                   Armin Catovic and
                   Marc Alencon and
-                  Michał Stęchły and
+                  Michał Stęchły and
                   Christian Bauer and
                   Lucas Otávio N. de Araújo and
                   JPW and
@@ -204,16 +166,16 @@ Here is a sample for BibTeX:
 }
 ```
 
-# Contact 📝
+</details>
+
+## Contact
 
 Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
 
 Codecarbon was formerly developed by volunteers from [**Mila**](http://mila.quebec) and the [**DataForGoodFR**](https://twitter.com/dataforgood_fr) community alongside donated professional time of engineers at [**Comet.ml**](https://comet.ml) and [**BCG GAMMA**](https://www.bcg.com/en-nl/beyond-consulting/bcg-gamma/default).
 
 Now CodeCarbon is supported by [**Code Carbon**](https://www.helloasso.com/associations/code-carbon), a French non-profit organization whose mission is to accelerate the development and adoption of CodeCarbon.
 
-## Star History
+### Star History
 
-Comparison of the number of stars accumulated by the different Python CO2 emissions projects:
 [![Star History Chart](https://api.star-history.com/svg?repos=mlco2/codecarbon,lfwa/carbontracker,sb-ai-lab/Eco2AI,fvaleye/tracarbon,Breakend/experiment-impact-tracker&type=Date)](https://star-history.com/#mlco2/codecarbon&lfwa/carbontracker&sb-ai-lab/Eco2AI&fvaleye/tracarbon&Breakend/experiment-impact-tracker&Date)
-