docs(packages): TOW-1588 add build_package documentation

[bradhe]

TOW-1588 — Document tower.packages.build_package

Tower CLI v0.3.49 introduced a native Rust-backed build_package in the tower.packages namespace. This PR adds clear documentation for this function so that users and contributors understand how to use it.

Changes

src/tower/packages/__init__.py

• Replaced bare re-export (from .._native import build_package) with a thin wrapper that carries a comprehensive NumPy-style docstring.
• Documents all four build pipeline steps (Towerfile Discovery → Native Resolution → Tokio Runtime → Artifact Generation), both arguments, the RuntimeError raise conditions, and a full usage example.

src/tower/_native.pyi

• Added a brief docstring to the type stub so that IDEs and type-checkers show useful hover text.

INSTALL-AND-REFERENCE.md

• Added a new Packages API top-level section after the Optional features block.
• Covers tower.packages.build_package with an argument table, step-by-step how-it-works table, error conditions, and a copyable code example.

No runtime changes

The wrapper is a zero-overhead thin delegation to the native function; no behaviour is changed.

Summary by CodeRabbit

Release Notes

• Documentation
  • Enhanced API documentation for the package building feature, including detailed reference materials, parameter descriptions, usage examples, and error handling information.

[github-actions]

⚠️ WARNING: This PR targets main instead of develop

This PR is targeting main which will trigger a production deployment when merged.

If this is a regular feature/fix PR, please change the base branch to develop.
If this is intentional (e.g., hotfix), you can ignore this warning.

Current base: main
Recommended base: develop

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 27235ce and 4b8fe4d.

📒 Files selected for processing (3)

• INSTALL-AND-REFERENCE.md
• src/tower/_native.pyi
• src/tower/packages/__init__.py

---

📝 Walkthrough

Walkthrough

Adds comprehensive documentation for the build_package API across documentation, type stubs, and Python implementation. Introduces a Python wrapper function around the native implementation while duplicating API documentation content in the reference file.

Changes

Cohort / File(s)	Summary
Documentation INSTALL-AND-REFERENCE.md	Added detailed "Packages API" section describing tower.packages.build_package in two locations, covering function signature, behavior, error conditions, implementation flow, parameters, examples, and archive structure.
Type Stubs src/tower/_native.pyi	Added comprehensive docstring to build_package function signature documenting purpose, parameters, return behavior, and RuntimeError conditions.
Python Wrapper src/tower/packages/__init__.py	Introduced Python wrapper function build_package that delegates to aliased native implementation _native_build_package, retaining public API while enabling expanded docstring documentation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Poem

🐰 A package so neat, all bundled with care,
Documentation blooms in the digital air,
With wrappers and stubs, both native and bright,
The tower stands tall, a magnificent sight! ✨

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/tow-1588-build-package-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

⚠️ WARNING: This PR targets main instead of develop

This PR is targeting main which will trigger a production deployment when merged.

If this is a regular feature/fix PR, please change the base branch to develop.
If this is intentional (e.g., hotfix), you can ignore this warning.

Current base: main
Recommended base: develop