搭建开发环境¶
要为 BeeWare Docs Tools 做出贡献，你需要建立一个开发环境。
先决条件¶
您需要安装以下依赖项。
BeeWare Docs Tools 需要 Python 3.10+ 。你还需要一种管理虚拟环境的方法（如 venv）。
你可以运行以下命令来验证所安装的 Python 版本：
$ python3 --version
如果安装了多个版本的 Python，你可能需要用带特定的版本号的命令（例如，python3.13）替换python3。
我们建议你避免使用最近发布的 Python 版本（即带有“.0 ”或“.1”微版本号的版本，如 3.14.0）。这是因为在 macOS 上支持 Python 所需的工具的支持版本经常滞后，导致其无法与最新发布的稳定 Python 版本使用。
BeeWare Docs Tools 需要 Python 3.10+ 。你还需要一种管理虚拟环境的方法（如 venv）。
你可以运行以下命令来验证所安装的 Python 版本：
$ python3 --version
如果安装了多个版本的 Python，你可能需要用带特定的版本号的命令（例如，python3.13）替换python3。
我们建议你避免使用最近发布的 Python 版本（即带有“.0”或“.1”微版本号的版本，如 3.14.0）。这是因为在 Linux 上支持 Python 所需的工具通常会在支持版本方面滞后，无法使用最近发布的 Python 稳定版本。
BeeWare Docs Tools 需要 Python 3.10+ 。你还需要一种管理虚拟环境的方法（如 venv）。
你可以运行以下命令来验证所安装的 Python 版本：
C:\...>py -3 --version
如果你安装了多个版本的 Python，可能需要用特定的版本号替换 -3（例如，-python3.13）
我们建议你避免使用最近发布的 Python 版本（即带有“.0 ”或“.1”微版本号的版本，如 3.14.0）。这是因为在 Windows 上支持 Python 所需的工具通常会在支持版本方面滞后，导致其无法与最新发布的稳定 Python 版本使用。
设置开发环境¶
为 BeeWare Docs Tools 设置开发环境的推荐方法是创建虚拟环境，并安装 BeeWare Docs Tools 的开发版本及其依赖项。
克隆 BeeWare Docs Tools 仓库¶
接下来，访问 GitHub 上的 BeeWare Docs Tools 页面，如果还没有的话，创建 BeeWare Docs Tools 在自己账户下的派生（fork）仓库。接下来，点击 fork 上的“<> Code”按钮。如果你的电脑上安装了 GitHub Desktop，可以选择“Open With GitHub Desktop”；否则，复制所提供的 HTTPS URL，然后用命令行将仓库克隆到你的电脑上：
创建 BeeWare Docs Tools 的派生（fork）版本库，然后：
$ git clone https://github.com/<你的用户名>/beeware-docs-tools.git
(代入 你的 GitHub 用户名）
创建 BeeWare Docs Tools 的派生（fork）版本库，然后：
$ git clone https://github.com/<你的用户名>/beeware-docs-tools.git
(代入 你的 GitHub 用户名）
创建 BeeWare Docs Tools 的派生（fork）版本库，然后：
C:\...>git clone https://github.com/<你的用户名>/beeware-docs-tools.git
(代入 你的 GitHub 用户名）
设置上游仓库¶
克隆派生（fork）存储库后，将 BeeWare 仓库添加名为 upstream（上游）的远程仓库。这使本地副本拥有对原始仓库的引用，便于以后同步更新。
你还需要从 upstream 仓库获取标签（tags），以便 Toga 和 Briefcase 等工具能够解析准确的当前版本号：
$ git remote add upstream https://github.com/beeware/beeware-docs-tools.git
$ git fetch --tags upstream
$ git remote add upstream https://github.com/beeware/beeware-docs-tools.git
$ git fetch --tags upstream
C:\...>git remote add upstream https://github.com/beeware/beeware-docs-tools.git
C:\...>git fetch --tags upstream
如果想在派生仓库中也存储这些标签，可将它们推送：
$ git push --tags
这在你后续创建新克隆时可能很有用，可让标签在您的派生仓库中可用。
创建虚拟环境¶
要建立虚拟环境并升级 pip，请运行
$ cd beeware-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip
$ cd beeware-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip
C:\...>cd beeware-docs-tools
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip
现在，你的提示符应该带有 (.venv) 前缀。
安装 BeeWare Docs Tools¶
有了源代码，就可以在开发环境中以编辑模式安装 BeeWare Docs Tools 了。运行以下命令：
(.venv) $ python -m pip install -U -e . --group dev
(.venv) $ python -m pip install -U -e . --group dev
(.venv) C:\...>python -m pip install -U -e . --group dev
启用 pre-commit¶
BeeWare Docs Tools 使用一个名为 pre-commit 的工具来识别简单问题并规范代码格式。它通过安装一个 git 钩子，以在完成任何 git 提交（commit）之前自动运行一系列代码 linter。要启用预提交，请运行：
(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit
(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit
(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit
现在，你可以开始对 BeeWare Docs Tools 进行贡献了！