使用 Gitpod 进行 pandas 开发#
文档的这一部分将指导你
使用 Gitpod 构建你的 pandas 开发环境
在 GitHub 上创建 pandas 仓库的个人分支
快速浏览 pandas 和 VSCode
在 Gitpod 中处理 pandas 文档
Gitpod#
Gitpod 是一个开源平台，用于自动化和即时可用的开发环境。它使开发者能够将他们的开发环境描述为代码，并直接从浏览器为每个新任务启动即时且全新的开发环境。这减少了安装本地开发环境和处理不兼容依赖的需求。
Gitpod GitHub 集成#
要使用 Gitpod，你需要在 GitHub 账户上安装 Gitpod 应用。如果你还没有 GitHub 账户，则需要先创建一个。
要开始使用，只需登录 Gitpod，并授予 GitHub 相应的权限。
我们已经构建了一个 Python 3.10 环境，所有开发依赖项将在环境启动时安装。
分支 pandas 仓库#
作为贡献者参与 pandas 开发的最佳方式是首先创建仓库的分支。
浏览到你的分支。你的分支将有一个类似 noatamir/pandas-dev 的 URL，其中
noatamir会替换为你的 GitHub 用户名。
启动 Gitpod#
通过 GitHub 验证 Gitpod 后，你可以安装 Gitpod Chromium 或 Firefox 浏览器扩展，它将在仓库的 Code 按钮旁边添加一个 Gitpod 按钮。
如果你安装了扩展，可以点击 Gitpod 按钮启动一个新的工作区。
另外，如果你不想安装浏览器扩展，可以访问 https://gitpod.io/#https://github.com/USERNAME/pandas，将
USERNAME替换为你的 GitHub 用户名。在这两种情况下，都会在你的网页浏览器中打开一个新标签页，并开始构建你的开发环境。请注意，这可能需要几分钟。
构建完成后，你将被导向你的工作区，其中包含 VSCode 编辑器以及处理 pandas 所需的所有依赖项。首次启动工作区时，你可能会注意到有一些操作正在运行。这将确保你安装了开发版本的 pandas。
当你的工作区准备就绪后，你可以通过输入以下命令来测试构建
$ python -m pytest pandas
请注意，此命令需要一些时间运行，因此一旦你确认它正在运行，你可能希望使用 ctrl-c 取消它。
快速工作区导览#
Gitpod 使用 VSCode 作为编辑器。如果你之前没有使用过这个编辑器，可以查阅 VSCode 入门指南 文档 来熟悉它。
你的工作区将看起来类似于下面的图片
我们在编辑器中标记了一些重要部分
你当前的 Python 解释器 - 默认情况下，它是
pandas-dev，应显示在状态栏和你的终端中。你无需激活 conda 环境，因为它会始终为你激活。你当前的分支始终显示在状态栏中。你也可以使用此按钮切换或创建分支。
GitHub 拉取请求扩展 - 你可以使用它在你的工作区中处理拉取请求。
市场扩展 - 我们为 pandas Gitpod 添加了一些必要的扩展。此外，你还可以为你安装其他扩展或语法高亮主题，这些都会为你保留。
你的工作区目录 - 默认情况下是
/workspace/pandas-dev。请勿更改此目录，因为它是 Gitpod 中唯一保留的目录。
我们还预装了一些工具和 VSCode 扩展，以帮助提升开发体验
使用 Gitpod 的开发工作流程#
本文档的贡献 pandas 部分包含有关 pandas 开发工作流程的信息。在开始贡献之前，请务必查阅此部分。
使用 Gitpod 时，git 已为你预先配置好
你无需配置 git 用户名和邮箱，因为通过 GitHub 认证后会自动为你完成。除非你使用了 GitHub 的隐私邮箱功能。你可以在终端中使用命令
git config --list查看 git 配置。使用git config --global user.email “your-secret-email@users.noreply.github.com”将你的邮箱地址设置为与你的 GitHub 个人资料关联的提交邮箱。由于你从自己的 pandas 分支启动了工作区，默认情况下会添加
upstream和origin作为远程仓库。你可以在终端中输入git remote或点击状态栏上的分支名称（参见下图）来验证。
渲染 pandas 文档#
你可以在如何构建 pandas 文档 部分找到使用 Sphinx 渲染文档的详细说明。要构建完整的文档，你需要在 /doc 目录中运行以下命令
$ cd doc
$ python make.py html
另外，你可以构建单个页面，使用
python make.py --single development/contributing_gitpod.rst
你有两种主要选项可以在 Gitpod 中渲染文档。
选项 1：使用 Liveserve#
在
pandas/doc/build/html中查看文档。要查看页面的渲染版本，你可以右键点击
.html文件，然后点击 Open with Live Serve（用 Live Serve 打开）。另外，你也可以在编辑器中打开文件，然后点击状态栏上的 Go live（上线）按钮。
编辑器右侧将打开一个简单的浏览器。我们建议关闭它，然后点击弹出窗口中的 Open in browser（在浏览器中打开）按钮。
要停止服务器，请点击状态栏上的 Port: 5500（端口：5500）按钮。
选项 2：使用 rst 扩展#
一种快速简便的方法，可以在编辑 .rst 文件时实时查看更改，即使用 rst 扩展和 docutils。
注意
这将生成文档的简单实时预览，不包含 html 主题，并且某些反向链接可能无法正确添加。但这是一种简单轻量级的方式，可以即时获取工作反馈，而无需构建 html 文件。
在编辑器中打开位于
doc/source中的任何源文档文件。在 Mac 上使用 Cmd-Shift-P 或在 Linux 和 Windows 上使用 Ctrl-Shift-P 打开 VSCode 命令面板。开始输入“restructured”并选择“Open preview”（打开预览）或“Open preview to the Side”（在侧边打开预览）。
在处理文档时，你将在编辑器上看到它的实时渲染。
如果你想查看包含 html 主题的最终输出，你需要使用 make html 重建文档，并使用选项 1 中描述的 Live Serve。
常见问题解答与故障排除#
我的 Gitpod 工作区会保留多久？#
如果你的工作区停止后不使用，将保留 14 天，之后会被删除。
我可以回到之前的工作区吗？#
是的，假设你离开了一段时间，现在想继续你的 pandas 贡献工作。你需要访问 https://gitpod.io/workspaces 并点击你想重新启动的工作区。你上次离开时的所有更改都将保留在那里。
我可以安装额外的 VSCode 扩展吗？#
当然可以！你安装的任何扩展都将安装在你自己的工作区并保留。
我已经在 Gitpod 上注册了，但在我的仓库中仍然看不到 Gitpod 按钮。#
前往 https://gitpod.io/integrations 并确保你已登录。将鼠标悬停在 GitHub 上，然后点击右侧出现的三个按钮。点击编辑权限，并确保勾选了 user:email、read:user 和 public_repo。点击 Update Permissions（更新权限）并在 GitHub 应用程序页面确认更改。
如果我不使用工作区，它会保持活动状态多久？#
如果你在浏览器标签页中保持工作区打开但不与其交互，它将在 30 分钟后关闭。如果你关闭浏览器标签页，它将在 3 分钟后关闭。
我的终端是空白的 - 没有光标，完全没有响应#
不幸的是，这是 Gitpod 方面的一个已知问题。你可以通过两种方式解决此问题
完全创建一个新的 Gitpod 工作区。
前往你的 Gitpod 控制面板，找到正在运行的工作区。将鼠标悬停在其上，点击三个点菜单，然后点击停止。工作区完全停止后，你可以点击其名称再次启动它。
我通过 GitHub 进行了身份验证，但仍然无法通过 Gitpod 提交到仓库。#
前往 https://gitpod.io/integrations 并确保你已登录。将鼠标悬停在 GitHub 上，然后点击右侧出现的三个按钮。点击编辑权限，并确保勾选了 public_repo。点击 Update Permissions（更新权限）并在 GitHub 应用程序页面确认更改。
致谢#
本页面略微改编自 NumPy 项目。