Improve documentation information architecture

[igerber]

Methodology references (required if estimator / math changes)

• Method name(s): none/ na. all doc changes
• Paper / source link(s):
• Any intentional deviations from the source (and why):

Validation

• Tests added/updated:
• Backtest / simulation / notebook evidence (if applicable):

Security / privacy

• Confirm no secrets/PII in this PR: confirmed

[github-actions]

Overall Assessment

✅ Looks good

This PR is documentation/config only. I found no methodology-affecting changes. There is one non-blocking documentation issue: the new notebook banner hardcodes GitHub main, so versioned docs can link users to notebook sources from a different revision than the page they are reading. Assessment is based on source review; I could not run a local Sphinx build because sphinx, nbsphinx, and pydata_sphinx_theme are not installed in this environment.

Executive Summary

• Verified the diff only touches documentation navigation, Sphinx config, and LLM-facing docs; no estimator code, defaults, weighting, variance/SE, or assumption logic changed.
• The homepage and API toctree reorganizations preserve page coverage and look internally consistent in docs/index.rst:L54-L110 and docs/api/index.rst:L217-L262.
• The version bump in docs/llms-full.txt:L5 matches package metadata in pyproject.toml:L5-L8 and diff_diff/init.py:L182-L182.
• P2: the new notebook banner links to blob/main in docs/conf.py:L110-L123, even though the same file already has ReadTheDocs version-awareness in docs/conf.py:L133-L145.

Methodology

• No findings. Affected methods: none. Cross-check against docs/methodology/REGISTRY.md is not triggered beyond confirming the PR does not change any estimator implementation, assumptions, weighting, or inference behavior.

Code Quality

• No findings.

Performance

• No findings.

Maintainability

• No findings. The IA refactor is straightforward, and the category split in docs/api/index.rst:L217-L262 improves scanability without changing content coverage.

Tech Debt

• No separate tech-debt findings. The notebook-link issue above is not currently tracked in TODO.md, so it remains unmitigated if deferred.

Security

• No findings. No secrets/PII are introduced, and the added HTML snippet only interpolates repo-controlled document paths.

Documentation/Tests

• P2 Impact: The notebook admonition always links to https://github.com/igerber/diff-diff/blob/main/..., so users reading stable, tagged, or non-main branch docs can land on notebook sources from a different revision, with examples/API usage that may not match the rendered page. Concrete fix: derive the GitHub ref from the same ReadTheDocs version metadata already read in docs/conf.py:L133-L145 and use that ref in the notebook URL instead of hardcoding main in docs/conf.py:L110-L123.