docs: complete metadata, citation, troubleshooting and accuracy docs

[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.

Related Issue

Fixes #1301

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, package metadata, 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 (5246 attributes). tests/test_cpu.py, tests/test_emissions_tracker.py and the new tests/test_readme_links.py pass (76 passed, 2 skipped). Ruff error count is unchanged from master.

Screenshots (if appropriate):

N/A

What is in here

Packaging and citation

• pyproject.toml: description, 15 keywords, 19 classifiers. bumpver also patterns CITATION.cff.
• 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. New tests/test_readme_links.py asserts relative links resolve.
• 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. cpu.py now appends a docs URL to the RAPL-permission and unknown-CPU warnings via one shared constant.

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. Release Drafter now takes the release number from [tool.bumpver] current_version in pyproject.toml.
• 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 with unresolved handles dropped, plus a collective "The CodeCarbon contributors" entry; this is a social decision, not a technical one.
• 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.

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/test 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 92.03%. Comparing base (e5e46ab) to head (1289626).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1302      +/-   ##
==========================================
+ Coverage   91.70%   92.03%   +0.33%     
==========================================
  Files          49       49              
  Lines        5157     5158       +1     
==========================================
+ Hits         4729     4747      +18     
+ Misses        428      411      -17     

☔ 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.