贡献给pygmtools：开发者文档

首先，感谢您为pygmtools做出贡献！

如何贡献

为pygmtools做贡献的首选工作流程是在GitHub上分叉主仓库，克隆并在一个分支上进行开发。步骤如下：

1. 通过点击页面右上角的“Fork”按钮来项目仓库。这将在您的GitHub用户账户下创建一个代码副本。有关如何fork仓库的更多详细信息，请参阅此指南。

2. 将你在GitHub账户上的仓库克隆到本地磁盘：

   $ git clone git@github.com:YourUserName/pygmtools.git
   $ cd pygmtools
   

3. 创建一个feature分支来保存您的开发更改：

   $ git checkout -b my-feature
   

   始终使用feature分支。永远不要在master分支上工作是一个好习惯！

4. 在你的功能分支上开发功能。使用git add添加更改的文件，然后git commit文件：

   $ git add modified_files
   $ git commit
   

   要在Git中记录您的更改，然后使用以下命令将更改推送到您的GitHub账户：

   $ git push -u origin my-feature
   

5. 按照这些说明从你的分支创建一个拉取请求。这将通过电子邮件通知提交者，并自动运行检查。

（如果上述任何内容对你来说像是魔法，请查阅网上的Git文档，或者向朋友或其他贡献者寻求帮助。）

拉取请求检查清单

我们建议您在提交拉取请求之前，您的贡献符合以下规则：

• 遵循PEP8指南。

• 如果你的拉取请求解决了一个问题，请在拉取请求标题中描述该问题，并在拉取请求描述中提到问题编号。这将确保创建一个指向原始问题的链接。

• 所有公共方法都应该有信息丰富的文档字符串，并在适当的时候以doctests的形式提供示例用法。

• 在添加额外功能时，请在该功能的API下提供至少一个示例脚本。可以参考其他功能的示例。还鼓励您将新示例添加到examples/文件夹中，以展示新功能在实际中的用途，并在可能的情况下与pygmtools中可用的其他方法进行比较。

  • 如果您修改了任何示例，请在提交之前构建文档，并请同时提交docs/auto_examples/中的任何更改。

• 文档和高覆盖率的测试对于接受增强是必要的。错误修复或新功能应提供非回归测试。这些测试验证修复或功能的正确行为。通过这种方式，代码库的进一步修改被保证与期望的行为一致。对于错误修复的情况，在提交PR时，这些测试应在主分支的代码库中失败，并在PR代码中通过。

• 至少有一段叙述性文档，包含对文献和示例的参考链接。

您还可以使用以下工具检查常见的编程错误：

• 没有pyflakes警告，请检查：

  $ pip install pyflakes
  $ pyflakes path/to/module.py
  

• 没有PEP8警告，请使用以下命令检查：

  $ pip install pep8
  $ pep8 path/to/module.py
  

• AutoPEP8 可以帮助你修复一些简单的冗余错误：

  $ pip install autopep8
  $ autopep8 path/to/pep8.py
  

提交错误报告

我们使用Github问题来跟踪所有错误和功能请求；如果您发现了一个错误或希望看到某个功能被实现，请随时打开一个问题。

建议在提交之前检查您的问题是否符合以下规则：

• 请确认您的问题目前没有被其他issues或pull requests处理。

• 请确保所有代码片段和错误消息都格式化为适当的代码块。 参见创建和突出显示代码块。

• 请包含您的操作系统类型和版本号，以及您的Python、pygmtools、numpy和scipy版本。如果您使用GPU，请提供您正在运行的后端名称以及GPU/CUDA版本。可以通过运行以下环境报告找到这些信息（pygmtools>=0.2.9）：

  $ python3 -c 'import pygmtools; pygmtools.env_report()'
  

  如果您正在使用GPU，请确保在运行上述脚本之前安装pynvml：pip install pynvml。

• 请具体说明涉及的估计器和/或函数以及数据的形状，如适用；请包含一个可复现的代码片段或链接到gist。如果引发异常，请提供回溯信息。

文档

我们很高兴接受任何类型的文档：函数文档字符串、reStructuredText文档、教程、示例等。reStructuredText文档位于源代码仓库中的doc/目录下。

您可以使用任何文本编辑器编辑文档，然后通过在docs/目录下输入make html来生成HTML输出。生成的HTML文件位于docs/_build/中，可以在任何网络浏览器中查看。examples/中的示例文件也会被构建。如果您想跳过构建示例，请使用命令make html-noplot。

为了构建文档，您将需要docs/requirements.txt中列出的包。请使用python==3.8以保持与在线read-the-doc构建器的一致性。如果您修改了任何示例，请在提交之前构建文档，并请同时提交docs/auto_examples/中的任何更改。

在编写文档时，重要的是在数学和算法细节之间保持良好的平衡，并向读者提供关于算法功能的直观理解。最好总是从一个小段落开始，用通俗易懂的语言解释该方法对数据的作用。

开发者注意事项

这里我们展示一些想法，以帮助开发者更好地理解我们的设计并为pygmtools做出贡献。

多个数值后端

pygmtools 支持多种后端，包括 numpy、pytorch、jittor、paddle，旨在满足更广泛的研究人员和从业者的需求。每个后端可能都有其优势和性能特点，因此为用户提供多种选择是有益的。

统一API

尽管支持多种后端，pygmtools 能够为其功能提供统一的 API。这使得用户更容易在不同后端之间切换，增强了其易用性和可维护性。

文档驱动开发

我们非常重视全面且用户友好的文档。pygmtools 应该包含使用示例、教程和每个组件的清晰解释，使用户和贡献者更容易理解和使用该工具包。

性能基准

我们在各种条件下比较算法和数值后端，旨在为用户提供经验数据，以指导他们选择最适合其特定用例的求解器/算法。

开源协作

强调开源原则和协作开发可能是一个关键思想。我们鼓励开放的讨论、同行评审和社区参与，以提高工具包的质量和范围。

本贡献指南深受scikit-learn团队的启发。