为 Ansible Navigator 贡献代码¶

一些背景信息

ansible-navigator 代码库不仅面向其用户，也面向当前和未来的开发者。随着时间的推移，我们采用了一些工具来帮助我们维护它以及您贡献代码。

mypy（帮助进行类型检查）
pylint（检查所有内容）
code-spell（防止代码中的拼写错误）
isort（排序导入语句）

注意

在早期开发周期中，我们决定使用 black 作为格式化工具，这就是为什么当前的 pull 请求需要通过源代码树的 `black --diff` 检查的原因。使用 `black` 的决定留给各个开发者，因为它所做的格式更改无需它也能实现。

下面详细介绍了如何手动运行这些工具，我们的 CI 也会为您检查它们。

为了贡献代码，您需要：

Fork 仓库。
创建一个分支，将您的更改推送到该分支。
将其作为 PR 发送给我们。
迭代您的 PR，整合所需的改进并参与讨论。

先决条件

拥有 {doc}tox <tox:index>。
使用 {doc}tox <tox:index> 运行测试。

在发送 PR 之前，请确保 `lint` 通过。

$ tox -e lint
lint create: .tox/lint
lint installdeps: .[test]
lint installed: ...
lint run-test-pre: PYTHONHASHSEED='4242713142'
lint run-test: commands[0] | pylint ansible_navigator tests ...
...
_________________________________ summary __________________________________
lint: commands succeeded
congratulations :)

注意

由于 Python 版本被固定到特定版本以确保本地运行 `tox -e lint` 的结果与 github actions 运行 `tox -e lint` 的结果相同，您可能会看到以下错误：`RuntimeError: failed to find interpreter for Builtin discover of python_spec='python3.XX'`。这表示需要安装哪个版本的 Python 才能本地运行 tox。在这种情况下，需要安装的 Python 版本是

Ansible Navigator 入门¶

从源代码构建和安装用于测试的软件包¶

克隆仓库后，在仓库根目录中创建一个并激活新的虚拟环境。完成此操作后，我们只需要从源代码安装 ansible-navigator。在工作区（navigator 的根文件夹）中使用以下命令。这将以可编辑/开发模式安装软件包及其测试所需的附加依赖项。

pip install -e .\[test]

如果出现任何错误，请尝试运行 `pip install --upgrade pip`。然后再次运行上述命令。

测试流程和示例¶

安装所有依赖项后，我们可以使用 pytest 执行测试。要运行文件 test_xyz.py 中的测试，我们需要导航到该文件。

示例：要运行单元测试“test_circular_imports.py”，我们将执行

pytest tests/unit/test_circular_imports.py

示例：要运行集成测试“test_stdout_vault.py”，我们将执行

pytest tests/integration/actions/exec/test_stdout_vault.py

等等……

此外，还可以利用 VSCode 测试树的功能，以更轻松和交互的方式运行和调试测试。`launch.json` 中提供了一个名为 **调试测试** 的专用配置，用于通过 VSCode 测试树交互式地调试测试。

将鼠标悬停在活动栏中的 **测试** 图标上以查看 VSCode 测试树。从那里展开并找到所需的单元或集成测试，然后适当地点击 `运行测试` 或 `调试测试`。

VSCode test tree

基本入口点概述和 src 文件摘要¶

src/ansible_navigator/cli.py 充当应用程序启动的主要入口点。
src/ansible_navigator/ui.py 包含 show() 函数，它是渲染 UI 的入口点。
src/ansible_navigator/actions 包含 ansible-navigator 可以执行的所有操作的实现（即其子命令），例如 run、collections、images、doc、inventory、settings 等等。
src/ansible_navigator/command_runner 命令运行器是围绕子进程的包装器，用于运行 shell 命令。
src/ansible_navigator/configuration_subsystem 此处包含从声明到处理的所有 CLI 参数背后的逻辑。
src/ansible_navigator/data 此目录包含非 Python 文件和将在执行环境中运行的独立脚本。
src/ansible_navigator/image_manager 包含与自省、访问、拉取容器镜像相关的所有操作。
src/ansible_navigator/runner 此处包含与 ansible-runner 交互的所有功能。
src/ansible_navigator/tm_tokenize 包含令牌化子系统，允许对 json 和 yaml 文件进行语法高亮显示。
src/ansible_navigator/ui_framework 包含我们用户界面的实现。
src/ansible_navigator/utils 包含应用程序中使用的所有常用实用程序。

配置 VSCode 设置¶

在安装了项目的 vscode 中，我们应该在工作区中看到一个 `.vscode` 文件夹。拥有 launch 配置文件是有益的，因为它允许我们配置和保存调试设置详细信息。VS Code 将调试配置信息保存在工作区（项目根文件夹）中 `.vscode` 文件夹中的 `launch.json` 文件中。

类似地，工作区设置文件 `settings.json` 也位于根文件夹中的 `.vscode` 文件夹下。这些是该项目的所有用户共享的项目特定设置。

使用现有设置或在这些 `launch.json` 和 `settings.json` 文件的配置中添加所需的更改。

现在，最后一步！

在需要的地方设置断点。
将鼠标悬停在活动栏中的 **运行和调试** 图标上以启动调试器。

此时，调试器应该命中您的断点并启动调试会话。

调试 Ansible-Navigator 子命令¶

Ansible-Navigator 带有一堆子命令。要调试任何特定子命令，请使用 **运行和调试** 下拉菜单从 `launch.json` 配置中选择相应的条目。我们在 `launch.json` 配置文件中添加 `args` 属性（传递给要调试的程序的参数）。

示例

要调试 `ansible-navigator run` 子命令，请使用 *args* 属性，在 *cwd* 中提供 playbook 名称和 playbook 的绝对路径。以下配置将允许调试 `ansible-navigator site.yml --mode stdout`。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug subcommand: run",
      "type": "python",
      "request": "launch",
      "module": "ansible_navigator",
      "args": ["run", "site.yml", "--mode", "stdout"],
      "cwd": "/home/user/../path/to/the/playbook",
      "justMyCode": false
    }
  ]
}

`launch.json` 文件中存在类似的配置条目来调试不同的子命令。在调试时从下拉菜单中选择一个条目，并在需要时进行修改。

有用链接¶

VS code 调试指南。
在 navigator 中使用 Python Debugger (pdb) 进行纯命令行调试。

贡献文档¶

文档源代码位于仓库根目录下的 docs 目录中。

我们使用 mkdocs 生成我们的文档网站。您可以通过执行以下命令在本地触发该过程：

$ tox -e docs
...

它也与 Read The Docs 集成，后者构建并发布对主分支的每个提交，并为每个 pull 请求生成实时文档预览。