Skip to content

pyproject.pyproject_wheel_doc_shipping

Category: pyproject  ·  Weight: 2

Invariant

Markdown docs intended to ship inside the built wheel must be wired through [tool.hatch.build.targets.wheel.force-include]. Without this wiring, hatchling excludes docs/*.md from the wheel and the published distribution is silently missing them.

When it fires

The check resolves the expected doc file list in this order:

  1. Explicit opt-in — [tool.axm-init.wheel-doc].files lists the doc files to ship. The check fails (passed=False, weight 2) if any listed file is not force-included.
  2. Auto-detection — when no explicit list is provided, every docs/*.md file on disk is treated as a shipping candidate. The check fails (passed=False, weight 2) if any auto-detected file is not force-included.
  3. No docs anywhere — passes silently.

To opt out entirely, declare an empty list: [tool.axm-init.wheel-doc] with files = [].

Configuration — [tool.axm-init.wheel-doc]

Key Type Default Description
files list[str] (auto-detect) Explicit list of doc paths (relative to project root) to ship in the wheel. An empty list disables the check.

Examples

Explicit opt-in

Declare exactly which docs ship in the wheel, then wire them through force-include:

TOML
[tool.axm-init.wheel-doc]
files = ["docs/index.md", "docs/quickstart.md"]

[tool.hatch.build.targets.wheel.force-include]
"docs/index.md" = "my_package/docs/index.md"
"docs/quickstart.md" = "my_package/docs/quickstart.md"

Auto-detection

With no [tool.axm-init.wheel-doc] block, every docs/*.md discovered on disk is expected to be force-included. For a project with docs/index.md and docs/api.md:

TOML
[tool.hatch.build.targets.wheel.force-include]
"docs/index.md" = "my_package/docs/index.md"
"docs/api.md" = "my_package/docs/api.md"

If one of the auto-detected files is missing from force-include, the check returns a failed result with a ready-to-paste fix snippet.

Opt out

For projects that intentionally do not ship docs inside the wheel:

TOML
[tool.axm-init.wheel-doc]
files = []

Scope and limitations

Auto-detection covers Markdown files directly in docs/, not nested pages. The implementation matches exact source keys in force-include; it does not inspect the built wheel or validate destination paths. CheckResult has no ERROR/WARNING severity field: explicit opt-in and auto-detection both affect the weighted score on failure.

A [tool.axm-init.wheel-doc] table without a files key currently behaves like an empty list. Omit the whole table to request auto-detection.