docs: restructure documentation using Diataxis framework

.github/PULL_REQUEST_TEMPLATE.md

@@ -20,7 +20,7 @@ What types of changes does your code introduce? Put an `x` in all the boxes that
 
 ## AI Usage Disclosure
 
-Please refer to [docs/contributing/AI_POLICY.md](https://github.com/mlco2/codecarbon/blob/master/docs/contributing/AI_POLICY.md) for detailed guidelines on how to disclose AI usage in your PR. Accurately completing this section is mandatory.
+Please refer to [docs/how-to/ai-policy.md](https://github.com/mlco2/codecarbon/blob/master/docs/how-to/ai-policy.md) for detailed guidelines on how to disclose AI usage in your PR. Accurately completing this section is mandatory.
 
 - [ ] 🟥 AI-vibecoded: You cannot explain the logic. Car analogy : the car drive by itself, you are outside it and just tell it where to go.
 - [ ] 🟠 AI-generated: Car analogy : the car drive by itself, you are inside and give instructions.
@@ -32,7 +32,7 @@ Go over all the following points, and put an `x` in all the boxes that apply.
 - [ ] My code follows the code style of this project.
 - [ ] My change requires a change to the documentation.
 - [ ] I have updated the documentation accordingly.
-- [ ] I have read the **[docs/contributing/CONTRIBUTING.md](https://github.com/mlco2/codecarbon/blob/master/docs/contributing/CONTRIBUTING.md)** document.
+- [ ] I have read the **[docs/how-to/contributing.md](https://github.com/mlco2/codecarbon/blob/master/docs/how-to/contributing.md)** document.
 - [ ] I have added tests to cover my changes.
 - [ ] All new and existing tests passed.
 

.github/copilot-instructions.md

@@ -1 +1 @@
-../docs/contributing/agents-instructions.md
+../docs/how-to/agent-instructions.md

.github/workflows/build-docs.yml

@@ -9,12 +9,12 @@ on:
     paths:
       - "docs/**"
       - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "scripts/check_docs_links.py"
+      - ".github/workflows/build-docs.yml"
   pull_request:
     branches: [master]
-    paths:
-      - "docs/**"
-      - "mkdocs.yml"
-      - ".github/workflows/build-docs.yml"
 
 jobs:
   build:
@@ -36,10 +36,11 @@ jobs:
       - name: Build docs
         run: |
           set -euo pipefail
-          # Run zensical and capture output, fail if command exits non-zero
           uv run zensical build -f mkdocs.yml --clean 2>&1 | tee docs_build.log
-          # If output contains common error indicators, fail the step.
           if grep -Ei "\b(error|failed|traceback|exception)\b" docs_build.log >/dev/null; then
             echo "Documentation build produced errors; failing workflow."
             exit 1
           fi
+
+      - name: Check documentation links (site/)
+        run: uv run python scripts/check_docs_links.py site

.github/workflows/deploy-docs.yml

@@ -14,6 +14,7 @@ on:
       - "scripts/deploy-docs.sh"
       - "codecarbon/_version.py"
       - "pyproject.toml"
+      - "scripts/check_docs_links.py"
   release:
     types: [published]
 
@@ -60,6 +61,9 @@ jobs:
       - name: Build docs
         run: uv run zensical build -f mkdocs.yml --clean
 
+      - name: Check documentation links
+        run: uv run python scripts/check_docs_links.py site
+
       - name: Deploy to GitHub Pages
         env:
           GITHUB_REPOSITORY: ${{ github.repository }}

AI_POLICY.md

@@ -1 +1 @@
-docs/contributing/AI_POLICY.md
+docs/how-to/ai_policy.md

CODE_OF_CONDUCT.md

@@ -1 +1 @@
-docs/contributing/CODE_OF_CONDUCT.md
+docs/how-to/code-of-conduct.md

CONTRIBUTING.md

@@ -0,0 +1 @@
+docs/how-to/contributing.md

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://docs.codecarbon.io/latest/getting-started/api/) before.
-- [Documentation](https://docs.codecarbon.io) 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://docs.codecarbon.io/latest/introduction/methodology/) 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://docs.codecarbon.io/latest/getting-started/installation/)
-
-## 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://docs.codecarbon.io/latest/getting-started/usage/)
+## 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 |
+| [Framework examples (scikit-learn)](https://docs.codecarbon.io/how-to/scikit-learn/) | Task-oriented ML framework examples |
+| [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://docs.codecarbon.io/) 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/docs/contributing/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)
-

SECURITY.md

@@ -1 +1 @@
-docs/contributing/SECURITY.md
+docs/how-to/security.md

codecarbon/cli/main.py

@@ -310,7 +310,7 @@ def config():
     overwrite_local_config("api_key", api_key, path=file_path)
     show_config(file_path)
     print(
-        "Consult [link=https://docs.codecarbon.io/latest/getting-started/usage/#configuration]configuration documentation[/link] for more configuration options"
+        "Consult [link=https://docs.codecarbon.io/latest/how-to/configuration/]configuration documentation[/link] for more configuration options"
     )
 
 

codecarbon/core/powermetrics.py

@@ -58,7 +58,7 @@ def _has_powermetrics_sudo() -> bool:
                 """Not using PowerMetrics, sudo password prompt detected.
                     If you want to enable Powermetrics please modify your sudoers file
                     as described in :
-                    https://docs.codecarbon.io/latest/introduction/methodology/#power-usage
+                    https://docs.codecarbon.io/latest/explanation/methodology/#power-usage
                 """
             )
             return False

codecarbon/external/ram.py

@@ -24,7 +24,7 @@ class RAM(BaseHardware):
     In V3, we need to improve the accuracy of the RAM power estimation.
     Because the power consumption of RAM is not linear with the amount of memory used,
 
-    See https://docs.codecarbon.io/latest/introduction/methodology/#ram for details on the RAM
+    See https://docs.codecarbon.io/latest/explanation/methodology/#ram for details on the RAM
     power estimation methodology.
 
     """