docs: clarify setup.py usage and activation

[RonnyPfannschmidt]

Summary

Fixes #1236

• Rewrites the setup.py section in docs/usage.md to make clear that setup.py should only be used for passing Python callables (custom version/local schemes) — all non-code configuration belongs in pyproject.toml
• Adds a complete working example showing the correct pattern: pyproject.toml for build requirements and config, setup.py only for the callable
• Removes references to the deprecated setup_requires mechanism
• Improves the "legacy simplified activation" note with clear, actionable remediation steps
• Adds a setup.py quick-start example to docs/index.md

Changes

docs/usage.md

• Renamed section from "Using the setup keyword" to "Using setup.py to pass code"
• Added warning admonition: "setup.py is not for configuration"
• Single example shows the proper split: pyproject.toml has [tool.setuptools_scm] for non-code config, setup.py passes only the callable
• Explains the use_scm_version entry point mechanism and that build-system.requires is the only supported approach
• Removed setup_requires mention (deprecated)
• Legacy activation note now lists concrete remediation options

docs/index.md

• Added setup.py quick-start example with clear framing (callable-only)

Test plan

• mkdocs build --clean --strict passes with no new warnings
• Pre-commit hooks pass
• Review rendered docs on ReadTheDocs preview

Made with Cursor

[Copilot]

Pull request overview

Updates the documentation to clarify the intended, modern way to use setup.py with setuptools-scm: only as a vehicle for passing Python callables (custom schemes), while keeping all non-code configuration and build requirements in pyproject.toml. This directly addresses confusion reported in #1236 around use_scm_version activation in isolated builds.

Changes:

• Rewrites the setup.py section in docs/usage.md to emphasize callable-only usage and add an end-to-end pyproject.toml + setup.py example.
• Adds an explanatory note on how use_scm_version is activated (entry point + build env dependency installation via build-system.requires).
• Adds a setup.py “callable-only” quick-start snippet to docs/index.md.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
docs/usage.md	Reframes setup.py guidance, adds complete example + activation explanation, and updates legacy activation remediation text.
docs/index.md	Adds a short setup.py snippet and links to the expanded usage section for the full pattern.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.