[davidberenstein1957]

Description

This PR completes twelve documentation and traction items: packaging/citation metadata, a rewritten examples index and RAPL guide, a new troubleshooting page, new accuracy and alternatives pages with a real bibliography, GitHub issue forms, a split contributing/development/maintaining doc set, a deprecations reference, and social-card/footer polish. Details are broken out by area below.

The non-docs parts (PyPI classifiers, the RAPL/CPU-model warning refactor, a docstring fix, Release Drafter wiring, and their tests) moved to #1431 at the maintainer's request, to keep this PR documentation-only.

Related Issue

Fixes #1301. Closes #1422.

Motivation and Context

The docs had drifted from the codebase: the examples index referenced symbols that no longer exist (CO2Tracker, @track_co2), citation metadata pinned an old release instead of tracking the latest one, there was no troubleshooting page tied to actual log lines, and accuracy/competitor claims were unsupported or unverified. This closes those gaps so the docs and issue templates match what the project actually does.

How Has This Been Tested?

uv run task docs builds clean and the internal link check passes. uv run bumpver update --dry --patch runs cleanly against the version references in CITATION.cff, README.md, and codecarbon/_version.py. Ruff error count is unchanged from master.

Screenshots (if appropriate):

N/A

What is in here

Packaging and citation

• pyproject.toml: bumpver now also patterns CITATION.cff and README.md so their version strings stay in sync at release time. (PyPI description/keywords/classifiers moved to chore: PyPI metadata, docs links in warnings, release-drafter versioning #1431.)
• New CITATION.cff and a rewritten README citation section using the Zenodo concept DOI 10.5281/zenodo.4658424, which tracks the latest release instead of pinning v2.4.1. docs/index.md citation link updated to the same DOI.

Discoverability

• examples/README.md rewritten as a categorised index, checked against ls examples/ and codecarbon/__init__.py. The duplicated table in docs/how-to/examples.md is gone; that page now points at the canonical index.
• The RAPL guide moves to a top-level how-to entry, retitled "Get accurate CPU measurements (Linux/RAPL)", with inbound links from the README, docs index, FAQ, installation and the quickstart.
• New docs/how-to/troubleshooting.md, keyed to log lines grepped out of the current source. Note: the RAPL-permission/unknown-CPU-model warning code in cpu.py that links to this page's anchors is in chore: PyPI metadata, docs links in warnings, release-drafter versioning #1431; those anchors need this PR merged for the links to resolve.

Supporting our claims

• New docs/explanation/alternatives.md and docs/explanation/accuracy.md. Accuracy figures are computed from CSVs already committed in this repo (codecarbon/data/hardware/cpu_load_profiling/); the TDP estimate deviates from RAPL by roughly -60% to +190% depending on CPU and load. Per-backend accuracy and wall-socket validation are marked "not yet measured". Competitor facts were pulled from the GitHub API; "peer-reviewed" softened to "accompanying academic paper" where the venue was not verified.
• methodology.md gains a bibliography; the personal blog post is demoted behind Khan et al. and Weaver; the open GitHub issue is relabelled as a tracked limitation.

Contribution and release surface

• Issue forms replace the three .md templates; the bug form requires codecarbon detect output.
• contributing.md split into a 95-line contributor page, how-to/development.md, and maintaining.md.
• New docs/reference/deprecations.md.
• Open Graph and Twitter Card tags via overrides/main.html, five footer links, and start()/stop()/flush()/task-tracking now rendering in the API reference.

Worth a maintainer's eye before merge

• CITATION.cff author list: names come from the existing README BibTeX. Entries that are only a GitHub handle with no real name on the profile are dropped; every real name is kept (Amine Saboni and Franklin Zhao were restored after review). A collective "The CodeCarbon contributors" entry is added.
• Two citations copied from the audit rather than verified against the papers: the Khan et al. RAPL in Action year/venue details, and the Henderson et al. JMLR volume/issue 21(248).
• External links were not fetched; the link checker skips them by default. Worth one scripts/check_docs_links.py site --external run.
• date-released in CITATION.cff still needs a manual touch at release time; bumpver only patterns the version line.
• Merge order with chore: PyPI metadata, docs links in warnings, release-drafter versioning #1431: merge this PR first. chore: PyPI metadata, docs links in warnings, release-drafter versioning #1431's warning messages link to troubleshooting-page anchors that only exist once this one is in.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Docs/refactor only.

AI Usage Disclosure

• 🟥 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.
• ⭐ AI-assisted. Car analogy : you drive the car, AI help you find your way.
• ♻️ No AI used. Car analogy : you drive the car.

Checklist:

• 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/how-to/contributing.md document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.66%. Comparing base (6175ec0) to head (c834772).
⚠️ Report is 11 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1302   +/-   ##
=======================================
  Coverage   93.66%   93.66%           
=======================================
  Files          50       50           
  Lines        5591     5591           
=======================================
  Hits         5237     5237           
  Misses        354      354           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[benoit-cty]

🤖 This review comment was written and posted by Claude Opus 5.5 (AI assistant), at the request of @benoit-cty. Findings were checked by reading the code and running tests locally (merged with current master where relevant), but please double-check before acting on them.

Verdict: 🔧 Request changes (rebase + a few fixes)

This is a large and mostly careful docs overhaul. The facts I spot-checked against the code hold up: the log strings, the 475 g world average, the PUE placement, the cubic/linear cpu_load models, and the unrounded coordinates in the CSV. I also recomputed the accuracy-table deviations from the committed profiling CSVs, and they match. Thanks!

Must fix:

1. Merge conflicts in docs/explanation/methodology.md, docs/explanation/rapl.md and docs/how-to/contributing.md. Since this branch was created, master has gained:
   • the RAPL mirror-dedup docs (db7ad55, 77db9bb, 3fcd4dc)
   • 73 lines of Conda-Forge publishing docs in contributing.md (6049252). After your split, those belong in docs/maintaining.md.
2. CITATION.cff:54 has version: 3.3.0, which will break bumpver. Master is at 3.3.1, and the new pattern '^version: {version}$' in [tool.bumpver.file_patterns] won't match, so the next release fails. date-released and the README BibTeX version = {3.3.0} are stale too.
3. Release drafter: maintainer direction (@benoit-cty). Rather than the label-based version-resolver (which makes enhancement/feature labels bump the minor version and changes release numbering; also, the breaking label doesn't exist in the repo), take the release number from pyproject.toml. For example, in .github/workflows/release-drafter.yml:

   - uses: actions/checkout@<sha>
   - id: version
     run: echo "version=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['tool']['bumpver']['current_version'])")" >> "$GITHUB_OUTPUT"
   - uses: release-drafter/release-drafter@<sha>
     with:
       version: ${{ steps.version.outputs.version }}
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

   Then keep name-template / tag-template: "v$RESOLVED_VERSION" and drop the version-resolver block. The version is dynamic (codecarbon/_version.py); [tool.bumpver] current_version is the single source bumpver keeps in sync.
4. The OG image URL returns 404 (overrides/main.html:16). config.site_url ~ "images/og-card.png" gives https://docs.codecarbon.io/images/og-card.png, but the docs are served under /latest/: /images/favicon.ico → 404, /latest/images/favicon.ico → 200. og:url from page.canonical_url is also missing /latest/. Include the version path in site_url, or build these URLs from the deployed base.
5. Content was deleted without being moved. The methodology rewrite drops "Estimation of Equivalent Usage Emissions": car 0.12 kg/km (EEA), TV 138 Wh/day (ADEME), US citizen 13.3 t/yr (IEA), with their sources. Those are the only documented sources for the dashboard's equivalence figures, so please keep them somewhere.
6. Broken link in code. codecarbon/core/powermetrics.py:73 still sends users to methodology/#power-usage, which no longer exists. The sudoers instructions moved to troubleshooting.md, so please update the URL.
7. The accuracy summary contradicts its own table. accuracy.md (the CPU load × TDP row) and the FAQ say "roughly −60 % to +90 %" / "factor of two in either direction". But the table shows E3-1240 v2 at +20 % to +187 % (confirmed from the CSV). Please widen the stated range.

Should split out, or call out explicitly:
8. These are not docs changes. Each is defensible, but they belong in separate PRs:

• the carbonserver/.../api_key_utils.py return type change to bytes, and the codeql[...] suppression
• the [tool.black] target-version pin
• blank_issues_enabled: false

9. The PR body is stale. It says a root CHANGELOG.md is added (it isn't), that there is no deprecations page (docs/reference/deprecations.md is added), that the Changelog URL "points at the docs" (it's unchanged), and mentions "four .md templates" (there were three).

Your own open items still stand: the CITATION author list, the unverified Khan et al. and Henderson citations, and the external link check.

Nits:

• The troubleshooting.md:88 heading still quotes "Please contact us.", but this PR changes that message to "Please help us add it, see …".
• Many pages cite exact file.py:NNN line numbers (output.md, methodology.md, accuracy.md). Several are already off, and they'll keep drifting. Function or class names are sturdier.
• codecarbon/data/hardware/cpu_load_profiling/E5-1240/ actually holds E3-1240 files. That's pre-existing, but accuracy.md relies on this data.

[davidberenstein1957]

Made the changes in 1289626: merged master, fixed CITATION version, release-drafter from pyproject, OG URLs, powermetrics link, accuracy range, restored equivalents; reverted the non-docs changes and refreshed the PR description.
Not done: file:line refs → function names and the E5-1240 folder rename (broad churn, better as a follow-up); CITATION authors, Khan/Henderson citations and the external link check still need a maintainer.

[benoit-cty]

🤖 Written and posted by Claude Opus 5.5 (AI assistant) at the request of @benoit-cty. Please double-check before acting.

This branch is now rebased on master (e159a68) and force-pushed: the new head is 5e147ef.

Why the build docs check failed
The failing run (35462c2) added track_emissions and the task APIs to the API reference. Their docstring fix (:param: tracker:) had been moved out to #1431. So griffe logged "Failed to parse field directive", and the workflow's grep for failed failed the job. #1431 has since landed on master (92a3a4c). After the rebase, the build logs no error lines and the internal link check passes.

Rebase

• @davidberenstein1957, your 5 commits and 2 merges are squashed into one commit authored by you (c4909ca). Replaying them linearly brought back conflicts you had already resolved, plus code that later moved to chore: PyPI metadata, docs links in warnings, release-drafter versioning #1431.
• Conflicts resolved:
  • contributing.md: master's new Webapp deployment section moved to maintaining.md.
  • methodology.md: master's Regional data section (US, Canada, Nordics, China) is kept next to the new carbon-intensity ladder.

Fixes from checking the docs against master (one commit each)

• 46c6444, methodology:
  • The Raspberry Pi 5 PMIC backend was missing from the CPU table and the component table; added it and renumbered the rows.
  • China was missing from the regional level of the intensity ladder.
  • A cloud region missing from impact.csv falls back through the whole location ladder, not only to the country value.
  • Machine-mode load comes from psutil.cpu_times() deltas (SystemCPULoadMeter), not cpu_percent().
  • About 60 file.py:NNN citations, most already stale, now use function names.
• 43729bf, troubleshooting: an undetected CPU gets the 85 W POWER_CONSTANT, not the per-thread default. Also fixed the unknown-CPU warning wording and a stale line reference.
• 5feec5a, output: the provenance table and the PUE note said the power columns are not PUE-scaled. They are, since v3.3.1, as the existing note on the same page says. Also added the Pi backend and the GPU power-sampling fallback.
• 8ad3d98, accuracy:
  • The default-TDP row is the same cpu_load curve with an assumed TDP.
  • powermetrics only runs on Apple Silicon when psutil is missing.
  • The E3-1240 v2 overshoot comes from the cubic (machine-mode) curve, not a linear one.
  • print_hardware.py names the backend only in its startup log.
• 1bf76eb, citation: CITATION.cff and the README BibTeX said 3.3.1, but master is 3.3.2. With the new bumpver patterns, the next release would have failed. Both now say 3.3.2, and date-released is 2026-10-23. bumpver update --dry --patch runs clean.
• ead7516: the accuracy sentence split the bullet list in enable-rapl.md; also replaced a stale line reference in rapl.md.
• 5e147ef: examples/README.md said the docs page mirrors it; the docs page links to it.
• Checked and correct: the deprecation versions (3.2.1, 3.2.8 and 3.1.1, against the tags), the log strings quoted in troubleshooting, the CLI defaults, and the RAM DIMM table and worked examples.

Validation

• zensical build and check_docs_links.py site pass, and pre-commit is clean.
• codecarbon/, tests/ and carbonserver/ are identical to master, so coverage is unchanged. The local test failures (RAPL permission tests when run as root, and one logging test that passes on its own) also exist on master.

Left for maintainers

• CITATION.cff / README author list: still open, and I left it unchanged. For example, handle-only contributors such as Inimaz were dropped.
• The Khan et al. and Henderson citation details are still unverified.
• External links are unchecked: run scripts/check_docs_links.py site --external.
• I did not check the competitor facts in alternatives.md.
• date-released needs a manual update at each release.
• The E5-1240 profiling folder rename is still to do.

---

Generated by Claude Code

[benoit-cty]

Huge improvements, thanks !