---
myst:
  enable_extensions:
    - attrs_block
  heading_anchors: '3'
---

# 为 ZOSPy 做出贡献

感谢您考虑为ZOSPy做出贡献！在做出贡献之前，请阅读这些指南，以便我们尽快处理您的贡献。

## 贡献想法

ZOSPy旨在通过为OpticStudio API提供Pythonic接口，使 Python 和 Zemax/Ansys OpticStudio 之间的交互尽可能简单。欢迎任何服务于此目标或帮助OpticStudio进行光学模拟的贡献。如果您不知道该贡献什么，以下是一些绝对受欢迎的想法：

1. 各种光学系统的示例（在`examples/`中）。这些必须以Jupyter Notebook的形式提供；
2. 实现额外的分析（在`zospy/analyses`中）。请参阅其他分析以了解如何实现它们。如果您添加新的分析，请同时包含单元测试；
3. 附加求解器的实现（在`zospy/solvers`中）。

## 代码风格

- 请根据[numpydoc]格式化您的文档字符串。
- 使用[ruff]检查并格式化你的代码。

所有格式均可自动应用（见下文）。提交 Pull 请求时将检查是否遵守这些准则。

## 工作流

### 1. 设置开发环境

ZOSPy 使用[Hatch]进行项目管理。要开始ZOSPy开发，请安装Hatch：

- [在Windows上安装 Hatch]

或者，您可以使用[`uv`]或[`pipx`]安装 Hatch：

```shell
# Using uv
uv tool install hatch

# Using pipx
pipx install hatch
```

接下来，打开项目目录并运行以下命令来设置开发环境：

```shell
hatch env create
```

### 2. 添加新功能

在新的功能分支中添加您的贡献。贡献分析时，请包含单元测试。

### 3. 格式化代码

要格式化代码，请在项目目录中运行以下命令：

```shell
hatch fmt
```

要格式化文档字符串，请运行以下命令：

```shell
hatch run format-docstrings
```

### 4. 测试

由于依赖OpticStudio，无法使用GitHub Actions进行自动测试，因此我们要求您在打开Pull请求之前运行所有单元测试。已针对多个Python版本实现了自动测试，可以通过运行以下命令启动

```shell
hatch test
```

在项目目录中。有关运行单元测试的更多信息，请参见[此处](unit_tests.md)。如果您运行以前未测试过的OpticStudio版本的测试或为分析包装器添加测试，请不要忘记为这些测试生成参考数据。有关此内容的更多信息，请参见[测试文档](./unit_tests.md#generating-test-reference-data)。

### 5. 打开Pull请求

打开一个拉取请求，等待我们的建议，并合并您的贡献！


[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html
[ruff]: https://astral.sh/ruff
[Hatch]: https://hatch.pypa.io/
[在 Windows 上安装 Hatch]: https://hatch.pypa.io/latest/install/#gui-installer_1
[`uv`]: https://docs.astral.sh/uv/
[`pipx`]: https://pipx.pypa.io/latest/installation/