2. 示例贡献#

2.1. 介绍#

如果您对skscope有更多经验，并且希望提高您的开源开发技能，下一步就是为skscope贡献示例。

示例库中的文档是一个长篇指南，展示了如何使用skscope来解决稀疏约束优化（SCO）问题。通常，在此文档中，我们将：

  • 描述问题及相关实际背景;

  • 向读者展示这个问题的数学公式以及基于skscope的相应实现；

  • 使用合成数据集或真实世界的数据集来验证实现。我们还可以与基准方法进行比较，以说明SCO和skscope的优势。

贡献可以是以下之一：

  1. 改进当前示例，例如，

    • 纠正拼写错误

    • 澄清概念

    • 合理推广当前方法以处理实际问题

    • 在数据集上应用以获得新的见解

或

  1. 贡献一个新颖的例子，有助于解决实践中有意义的问题。

2.2. 通用工作流程#

在大多数情况下，工作流程基于git。但如果您不熟悉命令行和git，我们建议您安装github桌面，它提供了一个用户友好的交互界面，以简化文档贡献。“github桌面”的工具在这里。

  1. 通过点击页面右上角的“Fork”按钮来分叉主仓库，这将在您的GitHub账户中创建一个副本；

  2. 通过Git将你的skscope分叉克隆到本地计算机；

    git clone https://github.com/YourAccount/skscope.git
cd skscope

  1. 在本地计算机上工作以贡献示例。

  2. 提交你对示例的改进/贡献：

    git add changed_files
git commit -m "YourContributionSummary"
git push

  3. 通过Github提交一个pull request，并解释你对文档的贡献。

接下来，我们将提供更多关于步骤3的详细信息，以便您更好地贡献示例。

2.3. 示例贡献流程#

在贡献示例之前，我们假设您已经完成了一般开发流程中描述的步骤1-2，并且您已经通过执行以下命令安装了必要的包。

pip install -r docs/requirements.txt

贡献示例有四个基本步骤：

  1. 如果您打算贡献一个新的示例，请在路径 docs/source/userguide/examples 中创建一个新的 .ipynb 文件。或者，如果您想改进现有的示例，请在相同的路径中找到相应的 .ipynb 文件。

  2. 在您希望贡献的.ipynb文件中编写相关内容。

  3. 转到docs目录（例如，通过cd docs），并在终端中运行以下命令：

    make html

此命令将在您的本地计算机上构建网页。请注意，这些网页是基于您最近的.ipynb文件内容构建的。您可以通过打开/刷新docs/build/html目录中的index.html文件来预览。

  1. 重复步骤2和步骤3，直到您对文档满意为止。

在完成步骤1-4之后，您几乎完成了示例贡献。为了确保它在在线网站上也能正常工作，请将PyPI中的依赖包添加到docs/requirements.txt中。