diff --git a/README.md b/README.md index f6edf1d..36d5d3b 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,12 @@ A command-line tool for analyzing PyTorch memory snapshots. Set a snapshot datab ## Installation -From a source checkout: - ```bash -pip install -e . +pip install pt-snap-cli ``` +For a source checkout and contributor setup, see [Development](#development). + ## Quick Start To start from a raw PyTorch memory snapshot, import the pickle into a SnapshotDB with pt-snap's built-in snapshot support, then list the available query templates: diff --git a/README_zh.md b/README_zh.md index ec177c9..c8f268a 100644 --- a/README_zh.md +++ b/README_zh.md @@ -6,12 +6,12 @@ ## 安装 -从源码 checkout 安装: - ```bash -pip install -e . +pip install pt-snap-cli ``` +源码 checkout 与贡献者安装见[开发](#开发)。 + ## 快速开始 > **安全警告:** 只导入来自可信来源的 pickle 快照。反序列化 pickle 可能执行任意代码; diff --git a/docs/en/mcp.md b/docs/en/mcp.md index a63388d..77502d1 100644 --- a/docs/en/mcp.md +++ b/docs/en/mcp.md @@ -6,13 +6,13 @@ ## Installation -From a source checkout: - ```bash -pip install -e . +pip install pt-snap-cli ``` -The MCP server is installed as part of the core package. +The MCP server is installed as part of the core package. Contributors working +from a source checkout can use `pip install -e ".[dev]"`; see +[Development](../../README.md#development) in the repository README. ## Starting the Server diff --git a/docs/en/quickstart.md b/docs/en/quickstart.md index f7344de..f03bace 100644 --- a/docs/en/quickstart.md +++ b/docs/en/quickstart.md @@ -6,12 +6,14 @@ Get up and running with `pt-snap-cli` in a few minutes. ## Installation -From a source checkout: - ```bash -pip install -e . +pip install pt-snap-cli ``` +This installs the `pt-snap` CLI. Contributors working from a source checkout can +use `pip install -e ".[dev]"`; see [Development](../../README.md#development) +in the repository README. + ## Your First Analysis ### Optional: Import a PyTorch Snapshot diff --git a/docs/zh/mcp.md b/docs/zh/mcp.md index b62666b..56e9d75 100644 --- a/docs/zh/mcp.md +++ b/docs/zh/mcp.md @@ -6,13 +6,12 @@ ## 安装 -从源码 checkout 安装: - ```bash -pip install -e . +pip install pt-snap-cli ``` -MCP 服务器作为核心包的一部分自动安装。 +MCP 服务器作为核心包的一部分自动安装。从源码 checkout 开发时,可使用 +`pip install -e ".[dev]"`;详见仓库 README 的[开发](../../README_zh.md#开发)一节。 ## 启动服务器 diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md index 7298731..5ca4106 100644 --- a/docs/zh/quickstart.md +++ b/docs/zh/quickstart.md @@ -6,12 +6,13 @@ ## 安装 -从源码 checkout 安装: - ```bash -pip install -e . +pip install pt-snap-cli ``` +这会安装 `pt-snap` 命令行工具。从源码 checkout 开发时,可使用 +`pip install -e ".[dev]"`;详见仓库 README 的[开发](../../README_zh.md#开发)一节。 + ## 第一次分析 ### 可选:导入 PyTorch 快照 diff --git a/tests/test_governance.py b/tests/test_governance.py index f3e3410..ec553d6 100644 --- a/tests/test_governance.py +++ b/tests/test_governance.py @@ -217,6 +217,31 @@ def test_old_source_identity_is_confined_to_fixed_evidence_allowlist() -> None: assert not unsupported_hits +USER_INSTALL_DOCS = ( + Path("README.md"), + Path("README_zh.md"), + Path("docs/en/quickstart.md"), + Path("docs/zh/quickstart.md"), + Path("docs/en/mcp.md"), + Path("docs/zh/mcp.md"), +) +PYPI_INSTALL = "pip install pt-snap-cli" +EDITABLE_DEV_INSTALL = 'pip install -e ".[dev]"' + + +def test_user_docs_prefer_pypi_install() -> None: + for path in USER_INSTALL_DOCS: + text = path.read_text() + pypi_at = text.find(PYPI_INSTALL) + editable_at = text.find("pip install -e") + assert pypi_at != -1, f"{path} must document `{PYPI_INSTALL}`" + if editable_at != -1: + assert pypi_at < editable_at, f"{path} must list PyPI install before editable install" + assert ( + EDITABLE_DEV_INSTALL in text or "Development" in text or "开发" in text + ), f"{path} must keep a contributor/source-install path" + + def test_bilingual_docs_record_split_and_pickle_security_contract() -> None: for path in (Path("docs/en/splitting.md"), Path("docs/zh/splitting.md")): text = path.read_text()