docs: port documentation to Markdown with Zensical theme (#1073)

* docs: port documentation to Markdown with Zensical theme

- Convert RST docs to Markdown format
- Add zensical.yml configuration
- Use CodeCarbon teal branding (matching logo)
- Fix index.md formatting
- Add proper headers and structure matching original RST

* chore: update documentation and configuration for Zensical theme

- Added deployment directory to .gitignore
- Updated CONTRIBUTING.md to reflect changes in documentation structure
- Replaced Sphinx with Zensical for documentation generation
- Updated README and other documentation files to align with new structure
- Removed obsolete zensical.toml and related files
- Adjusted build commands in pyproject.toml for Zensical integration

---------

Co-authored-by: Amine Saboni <saboni.amine@gmail.com>
Co-authored-by: inimaz <93inigo93@gmail.com>

* refactor(tests): format assertion for better readability in test_emissions_tracker_constant

- Updated the assertion for cpu_power to improve code clarity by breaking it into multiple lines.

* docs: add standalone installer instructions for non-Python users

- Included instructions for downloading and running a standalone installer using curl for Unix-based systems and PowerShell for Windows users.
- Updated command line section header to include an anchor for easier navigation.

* ci: add GitHub Actions workflows for documentation build and deployment

- Introduced `build-docs.yml` to automate Sphinx and Zensical documentation builds on push and pull request events.
- Added `deploy-docs.yml` for deploying documentation to GitHub Pages with versioning on master branch pushes and release events.
- Configured Python environment and dependencies for both workflows.

* ci: update deploy-docs workflow to include script path and fix pip command

- Added the path for `scripts/deploy-docs.sh` to the workflow triggers.
- Corrected the pip installation command by removing the 'uv' prefix for clarity.

* ci: update deploy-docs workflow to include script path and fix pip command

- Added the path for `scripts/deploy-docs.sh` to the trigger paths in `deploy-docs.yml`.
- Corrected the command to install dependencies from `uv pip install` to `pip install` for proper execution.

* ci: refactor build-docs workflow to streamline documentation build process

- Consolidated Sphinx and Zensical build steps into a single job.
- Updated paths to trigger on changes to `mkdocs.yml` instead of `zensical.toml`.
- Replaced Sphinx build commands with Zensical commands for documentation generation.
- Adjusted Python version setup and dependency installation using `uv` for improved compatibility.

* ci: update workflows to enhance documentation build and deployment

- Added permissions for read access in `build-docs.yml` and adjusted the build command to use `uv run`.
- Updated `deploy-docs.yml` to set permissions for write access and modified the version retrieval command to utilize `uv run` for consistency in execution.

* docs(quickstart): add login and no-api guidance in markdown docs

* fix(docs): address PR review comments

- usage.md: remove def_list colon, fix indentation, remove escaping
- comet.md, api.md: remove unnecessary escaping
- rapl.md: fix Threadripper measurements formatting
- output.md: add CodeCarbon API and Logfire sections
- faq.md: update API data answer, link to methodology for hardware
- mkdocs.yml: edit_uri master, Parameters nav label, add test_on_scaleway

Made-with: Cursor

* docs: update parameter documentation and fix formatting issues

- Removed `grafana_token` parameter from the parameters table in `parameters.md`.
- Corrected formatting inconsistencies in `methodology.md` and `visualize.md`, including adjustments to bullet points and mathematical expressions for clarity.

* docs: enhance documentation and update mkdocs configuration

- Added mkdocstrings plugin for improved documentation generation with Python support.
- Updated navigation in mkdocs.yml to include the Parameters section.
- Enhanced parameter descriptions in emissions_tracker.py for clarity and consistency.
- Corrected minor typos in API and parameters documentation.
- Introduced new check-docs-drift script in pyproject.toml for documentation consistency checks.

* chore: update dependencies and workflow configurations

- Added `setuptools` to the `dev` dependencies in `pyproject.toml` for improved package management.
- Updated `uv.lock` to include specific versions of `setuptools` based on Python version compatibility.
- Modified `build-docs.yml` to restrict branch triggers to `master` only, simplifying the workflow.

* fix: add new line back between 1: & 2:

* chore: add new lines for improved readability in various scripts

- Added new lines in `check_powerstat_approach.py`, `intel_rapl_show.py`, `test_default_dram.py`, `test_dram_option.py`, `test_rapl_domains.py`, and `test_rapl_fix.py` for better code organization and readability.
- Fixed formatting in `emissions_tracker.py` to ensure consistent spacing in parameter documentation.

---------

Co-authored-by: Patrick LLORET <plloret@hyperlex.fr>
Co-authored-by: Amine Saboni <saboni.amine@gmail.com>
Co-authored-by: inimaz <93inigo93@gmail.com>
Co-authored-by: inimaz <49730431+inimaz@users.noreply.github.com>
Co-authored-by: benoit-cty <anne@onyme.fr>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: LarytheLord <llawlietbagsum@gmail.com>
Co-authored-by: Amine Saboni <43726203+SaboniAmine@users.noreply.github.com>

Author: 7 people

.github/copilot-instructions.md

@@ -38,7 +38,7 @@ Here's what you need to know to navigate and contribute effectively.
 ### Key Directories
 
 - **tests/** - Unit tests for the core package
-- **docs/** - Sphinx documentation (build with `uv run task docs`)
+- **docs/** - Zensical documentation (build with `uv run task docs`)
 - **examples/** - Usage examples and demos
 - **deploy/** - Deployment configurations and scripts
 

.github/pyproject_versions.py

@@ -35,7 +35,7 @@ def get_version_from_file(filepath: str, pattern: str) -> str:
 
 def get_all_versions() -> dict:
     """
-    Read versions from all three files managed by bumpver.
+    Read versions from files managed by bumpver.
 
     :return: Dict containing versions from all files
     """
@@ -60,11 +60,6 @@ def get_all_versions() -> dict:
         "codecarbon/_version.py", r'^__version__\s*=\s*["\']([^"\']+)["\']'
     )
 
-    # Get version from docs/edit/conf.py
-    versions["docs_conf"] = get_version_from_file(
-        "docs/edit/conf.py", r'^release\s*=\s*["\']([^"\']+)["\']'
-    )
-
     return versions
 
 
@@ -95,7 +90,6 @@ def check_version_coherence(quiet=False) -> bool:
                 file_mapping = {
                     "pyproject_toml": "pyproject.toml [tool.bumpver] current_version",
                     "codecarbon_version": "codecarbon/_version.py __version__",
-                    "docs_conf": "docs/edit/conf.py release",
                 }
                 logging.error(f"  {file_mapping[file_key]}: {version}")
             logging.error(

.github/workflows/build-docs.yml

@@ -0,0 +1,36 @@
+name: Build Documentation
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  pull_request:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --group doc
+
+      - name: Build docs
+        run: uv run zensical build -f mkdocs.yml --clean

.github/workflows/deploy-docs.yml

@@ -0,0 +1,69 @@
+# Deploys docs to GitHub Pages with versioning.
+# Configure GitHub Pages: Settings > Pages > Source = "Deploy from a branch" > Branch = gh-pages
+
+# Docs deploy to gh-pages with versioning. Set Pages: Settings > Pages > Source = gh-pages branch.
+
+name: Deploy documentation
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "scripts/deploy-docs.sh"
+      - "codecarbon/_version.py"
+      - "pyproject.toml"
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: deploy-docs
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # push to gh-pages
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --group doc
+
+      - name: Get version
+        id: version
+        run: |
+          if [[ "${{ github.event_name }}" == "release" ]]; then
+            VERSION="${{ github.event.release.tag_name }}"
+            VERSION="${VERSION#v}"
+          else
+            VERSION=$(uv run python -c "from codecarbon._version import __version__; print(__version__)")
+          fi
+          echo "full=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Build docs
+        run: uv run zensical build -f mkdocs.yml --clean
+
+      - name: Deploy to GitHub Pages
+        env:
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          chmod +x scripts/deploy-docs.sh
+          scripts/deploy-docs.sh "${{ steps.version.outputs.full }}"

.gitignore

@@ -103,6 +103,7 @@ venv.bak/
 
 # mkdocs documentation
 /site
+/deploy
 
 # mypy
 .mypy_cache/

CONTRIBUTING.md

@@ -4,33 +4,34 @@
 
 <!-- TOC start (generated with https://github.com/derlin/bitdowntoc) -->
 
-- [</a> Have a Question?](#have-a-question)
-- [</a> Found a Bug?](#found-a-bug)
-- [</a> Have a Feature Request?](#have-a-feature-request)
-- [Alternative ways of contributing](#alternative-ways-of-contributing)
-- [</a> Ready to Contribute!](#ready-to-contribute)
-   * [Installation](#installation)
-   * [Some UV commands](#some-uv-commands)
-   * [Tests](#tests)
-   * [Stress your computer](#stress-your-computer)
-   * [Update all dependancies](#update-all-dependancies)
-   * [Branching and Pull Requests](#branching-and-pull-requests)
-   * [Debug in VS Code](#debug-in-vs-code)
-   * [Coding style && Linting](#coding-style-linting)
-   * [Dependencies management](#dependencies-management)
-   * [Build Documentation 🖨️](#build-documentation)
-   * [Release process](#release-process)
-      + [Test the build in Docker](#test-the-build-in-docker)
-- [API and Dashboard](#api-and-dashboard)
-   * [CSV Dashboard](#csv-dashboard)
-   * [Web dashboard](#web-dashboard)
-   * [API](#api)
-   * [Test the API](#test-the-api)
-   * [Restore database from a production Backup](#restore-database-from-a-production-backup)
-   * [Deployment](#deployment)
-      + [API](#api-1)
-      + [Dashboard](#dashboard)
-- [License](#license)
+- [Contributing to Code Carbon](#contributing-to-code-carbon)
+  - [ Have a Question?](#-have-a-question)
+  - [ Found a Bug?](#-found-a-bug)
+  - [ Have a Feature Request?](#-have-a-feature-request)
+  - [Alternative ways of contributing](#alternative-ways-of-contributing)
+  - [ Ready to Contribute!](#-ready-to-contribute)
+    - [Installation](#installation)
+    - [Some UV commands](#some-uv-commands)
+    - [Tests](#tests)
+    - [Stress your computer](#stress-your-computer)
+    - [Update all dependancies](#update-all-dependancies)
+    - [Branching and Pull Requests](#branching-and-pull-requests)
+    - [Debug in VS Code](#debug-in-vs-code)
+    - [Coding style \&\& Linting](#coding-style--linting)
+    - [Dependencies management](#dependencies-management)
+    - [Build Documentation 🖨️](#build-documentation-️)
+    - [Release process](#release-process)
+      - [Test the build in Docker](#test-the-build-in-docker)
+  - [API and Dashboard](#api-and-dashboard)
+    - [CSV Dashboard](#csv-dashboard)
+    - [Web dashboard](#web-dashboard)
+    - [API](#api)
+    - [Test the API](#test-the-api)
+    - [Restore database from a production Backup](#restore-database-from-a-production-backup)
+    - [Deployment](#deployment)
+      - [API](#api-1)
+      - [Dashboard](#dashboard)
+  - [License](#license)
 
 <!-- TOC end -->
 
@@ -225,7 +226,7 @@ Here is the launch.json to be able to debug examples and tests:
 
 Then run opened test with this button:
 
-![vscode_debug](docs/edit/images/vscode_debug.png)
+![vscode_debug](docs/images/vscode_debug.png)
 
 
 <!-- TOC --><a name="coding-style-linting"></a>
@@ -271,15 +272,40 @@ Dependencies are defined in different places:
 ### Build Documentation 🖨️
 
 No software is complete without great documentation!
-To make generating documentation easier, we use [`sphinx` package](https://www.sphinx-doc.org/en/master/usage/installation.html#installation-from-pypi).
+To make generating documentation easier, we use [Zensical](https://zensical.org/).
 
-In order to make changes, edit the `.rst` files that are in the `/docs/edit` folder, and then run in root folder:
+In order to make changes, edit the `.md` files in the `/docs` folder, and then run in root folder:
 
 ```sh
 uv run --only-group doc task docs
 ```
 
-to regenerate the html files.
+to regenerate the html files. For local preview with live reload, run `uv run --only-group doc task docs-serve`.
+
+### Rebase your branch on master 
+
+Before creating a PR, please make sure to rebase your branch on master to avoid merge conflicts and make the review easier. You can do it with the following command:
+```sh
+# Be careful, this command will delete every local changes you have, make sure to commit or stash them before running it
+TARGET_BRANCH=master
+current_branch=$(git symbolic-ref --short HEAD)
+git switch $TARGET_BRANCH && git pull
+git switch $current_branch --force && git fetch origin $TARGET_BRANCH
+git rebase $TARGET_BRANCH
+```
+
+In case of a conflict during a rebase, "incoming" refers to your branch, and "current" refers to master. This is because the commits from your branch are being applied to master, so they are incoming. In case of a merge, it's the opposite!
+
+Check if everything is fine:
+
+```sh
+git status
+```
+
+Push force
+```sh
+git push --force-with-lease
+```
 
 ### Rebase your branch on master 
 
@@ -313,7 +339,7 @@ git push --force-with-lease
 - Create a PR bumping the version with `uv run bumpver update --patch`. For a release candidate, use `uv run bumpver update --set-version 3.0.0_rc1`.
 - Run `uv run python .github/pyproject_versions.py -c` to check version consistancy.
 - Update the dependencies with `uv sync --upgrade`
-- [Build Documentation](#documentation) with `uv run --only-group doc task docs`.
+- [Build Documentation](#build-documentation) with `uv run --only-group doc task docs`.
 - Push the changes.
 - Merge the PR.
 - Wait for the Github Action `ReleaseDrafter` to finish running on the merge commit.

README.md

@@ -1,4 +1,4 @@
-![banner](docs/edit/images/banner.png)
+![banner](docs/images/banner.png)
 
 Estimate and track carbon emissions from your computer, quantify and analyze their impact.
 
@@ -22,14 +22,18 @@ CodeCarbon websites:
 
 - [About CodeCarbon 💡](#about-codecarbon-)
 - [Quickstart 🚀](#quickstart-)
-    - [Installation 🔧](#installation-)
-    - [Start to estimate your impact 📏](#start-to-estimate-your-impact-)
-      - [Monitoring your whole machine](#monitoring-your-machine-)
-      - [In your python code](#in-your-python-code-)
-      - [Visualize](#visualize-)
+  - [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)
 
 # About CodeCarbon 💡
 
@@ -45,7 +49,7 @@ At **CodeCarbon**, we believe, along with Niels Bohr, that "Nothing exists until
 
 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.
 
-![calculation Summary](docs/edit/images/calculation.png)
+![calculation Summary](docs/images/calculation.png)
 
 We explain more about this calculation in the [**Methodology**](https://mlco2.github.io/codecarbon/methodology.html#) section of the documentation.
 
@@ -128,7 +132,7 @@ There is other ways to use **codecarbon** package, please refer to the documenta
 ## Visualize 📊
 
 You can now visualize your experiment emissions on the [dashboard](https://dashboard.codecarbon.io/).
-![dashboard](docs/edit/images/dashboard.png)
+![dashboard](docs/images/dashboard.png)
 
 
 > Hope you enjoy your first steps monitoring your carbon computing impact!