使用 Gitpod 进行 pandas 开发

文档的这一部分将指导您完成：

• 将 Gitpod 用于您的 pandas 开发环境

• 在 GitHub 上创建 pandas 存储库的个人分支

• pandas 和 VSCode 快速浏览

• 在 Gitpod 中处理 pandas 文档

gitpod

Gitpod是一个用于自动化和可立即编码的开发环境的开源平台。它使开发人员能够将他们的开发环境描述为代码，并直接从浏览器为每个新任务启动即时和全新的开发环境。这减少了安装本地开发环境和处理不兼容依赖项的需要。

Gitpod GitHub 集成

为了能够使用 Gitpod，您需要在 GitHub 帐户上安装 Gitpod 应用程序，因此如果您还没有帐户，则需要先创建一个帐户。

要开始使用，只需登录Gitpod，并向 GitHub 授予适当的权限。

我们已经构建了 python 3.10 环境，所有开发依赖项将在环境启动时安装。

分叉 pandas 存储库

作为贡献者处理 pandas 的最佳方法是首先创建存储库的分支。

1. 浏览GitHub 上的 pandas 存储库并创建您自己的 fork。

2. 浏览到您的 fork。你的 fork 将有一个像noatamir/pandas-dev这样的 URL ，除了你的 GitHub 用户名代替 noatamir。

启动 Gitpod

通过 GitHub 对 Gitpod 进行身份验证后，您可以安装 Gitpod Chromium 或 Firefox 浏览器扩展 ，这将在存储库中的“代码”按钮旁边添加一个Gitpod按钮：

1. 如果您安装了扩展 - 您可以单击Gitpod按钮来启动新的工作区。

2. 或者，如果您不想安装浏览器扩展，可以访问https://gitpod.io/#https://github.com/USERNAME/pandas并替换 USERNAME为您的 GitHub 用户名。

3. 在这两种情况下，这都会在您的网络浏览器上打开一个新选项卡并开始构建您的开发环境。请注意，这可能需要几分钟的时间。

4. 构建完成后，您将被引导到工作区，包括 VSCode 编辑器以及处理 pandas 所需的所有依赖项。第一次启动工作区时，您会注意到可能正在运行一些操作。这将确保您安装了 pandas 的开发版本。

5. 当您的工作区准备就绪时，您可以通过输入以下内容来测试构建：

   $ python -m pytest pandas
   

   请注意，此命令需要一段时间才能运行，因此一旦确认它正在运行，您可能需要使用 ctrl-c 取消它。

快速工作区游览

Gitpod 使用 VSCode 作为编辑器。如果您之前没有使用过此编辑器，可以查看VSCode 入门文档来熟悉它。

您的工作区将类似于下图：

我们在编辑器中标记了一些重要的部分：

1. 您当前的 Python 解释器 - 默认情况下，它pandas-dev应该显示在状态栏和终端上。您不需要激活 conda 环境，因为它将始终为您激活。

2. 您当前的分支始终显示在状态栏中。您还可以使用此按钮更改或创建分支。

3. GitHub Pull Requests 扩展 - 您可以使用它来处理工作区中的 Pull Request。

4. 市场扩展 - 我们为 pandas Gitpod 添加了一些必要的扩展。不过，您还可以为您的用户安装其他扩展或语法突出显示主题，并且这些将为您保留。

5. 您的工作区目录 - 默认情况下，它是/workspace/pandas-dev.不要更改它，因为这是 Gitpod 中保留的唯一目录。

我们还预装了一些工具和 VSCode 扩展来帮助提升开发体验：

• VSCode 第一个扩展

• Markdown 多合一

• VSCode Gitlens 扩展

• VSCode Git 图形扩展

使用 Gitpod 的开发工作流程

本文档的“为 pandas 做贡献”部分包含有关 pandas 开发工作流程的信息。在进行您的贡献之前，请务必检查这一点。

使用 Gitpod 时，git 已为您预先配置：

1. 您不需要配置您的 git 用户名和电子邮件，因为当您通过 GitHub 进行身份验证时，这应该为您完成。除非您使用 GitHub 功能来保密电子邮件地址。您可以使用终端中的命令检查 git 配置。用于 将您的电子邮件地址设置为您用于通过 github 个人资料进行提交的地址。git config --listgit config --global user.email “your-secret-email@users.noreply.github.com”

2. 当您从自己的 pandas fork 启动工作区时，默认情况下，您将同时拥有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

1. 查看 中的文档pandas/doc/build/html。

2. 要查看页面的渲染版本，您可以右键单击该.html 文件，然后单击“使用 Live Serve 打开”。或者，您可以在编辑器中打开文件，然后单击状态栏上的“上线”按钮。

3. 编辑器的右侧将打开一个简单的浏览器。我们建议关闭它并单击弹出窗口中的“在浏览器中打开”按钮。

4. 要停止服务器，请单击状态栏上的端口：5500按钮。

选项 2：使用第一个扩展

.rst在处理文件时，可以使用带有 docutils 的第一个扩展名来快速轻松地查看文件中的实时更改。

笔记

这将生成没有主题的文档的简单实时预览 html，并且某些反向链接可能无法正确添加。但这是一种简单、轻量级的方法，无需构建 html 文件即可获得工作的即时反馈。

1. doc/source打开编辑器中的任何源文档文件。

2. 在 Mac 或 Linux 和 Windows 中打开 VSCode Command Palette 。开始输入“重组”，然后选择“打开预览”或“在侧面打开预览”。Cmd-Shift-PCtrl-Shift-P

3. 当您处理文档时，您将在编辑器上看到它的实时渲染。

如果您想查看主题的最终输出，html您将需要重建文档并使用 Live Serve，如选项 1 中所述。make html

常见问题解答和故障排除

我的 Gitpod 工作区会保留多长时间？

您停止的工作区将保留 14 天，如果您不使用它们，之后将被删除。

我可以返回之前的工作空间吗？

是的，假设您离开了一段时间，并且想继续为 pandas 做出贡献。您需要访问https://gitpod.io/workspaces并单击要再次启动的工作区。您的所有更改都将保留在您上次离开时​​的位置。

我可以安装额外的 VSCode 扩展吗？

绝对地！您安装的任何扩展都将安装在您自己的工作区中并保留。

我在 Gitpod 上注册了，但在我的存储库中仍然看不到Gitpod按钮。

前往https://gitpod.io/integrations并确保您已登录。将鼠标悬停在 GitHub 上并单击右侧出现的三个按钮。单击编辑权限并确保您已选中user:email、 read:user和public_repo。单击“更新权限” 并在 GitHub 应用程序页面中确认更改。

如果我不使用我的工作区，它会保持活动状态多长时间？

如果您在浏览器选项卡中保持工作区打开但不与之交互，它将在 30 分钟后关闭。如果您关闭浏览器选项卡，它将在 3 分钟后关闭。

我的终端是空白的 - 没有光标并且完全没有响应

不幸的是，这是 Gitpod 方面的一个已知问题。您可以通过两种方式来解决这个问题：

1. 完全创建一个新的 Gitpod 工作区。

2. 前往Gitpod 仪表板并找到正在运行的工作区。将鼠标悬停在其上并单击三点菜单 ，然后单击“停止”。当工作区完全停止时，您可以单击其名称再次重新启动它。

我通过 GitHub 进行了身份验证，但仍然无法通过 Gitpod 提交到存储库。

前往https://gitpod.io/integrations并确保您已登录。将鼠标悬停在 GitHub 上并单击右侧出现的三个按钮。单击编辑权限并确保您已public_repo选中。单击“更新权限”并在 GitHub 应用程序页面中确认更改。

致谢

此页面稍微改编自NumPy项目。