贡献者指南#

新手贡献者简要路线图#

nx-guides 的目标是提供关于图论、网络分析和 NetworkX 实现（算法等）的教学性 Notebook。这是开始参与开源贡献的好地方！

如果您想为 nx-guides 做出贡献并且已经确定了要处理的主题，接下来的步骤如下：

将 nx-guides 仓库克隆到您的本地机器。
将您的 markdown Notebook 添加到适当的文件夹（例如，如果您要添加新算法，请在 nx-guides/content/algorithms 中按照其他算法的结构添加一个以该算法名称命名的文件夹）。
确保您的 Notebook 符合本文档中的格式指南。
对图像和数据使用子目录。如果您使用任何静态图像和数据，请将它们放在相应的文件夹下。（可选）
将您的 Notebook 路径添加到 index.md 文件。
完成工作并准备就绪后，将您的更改推送到仓库并打开一个 PR（拉取请求）以供审查。
参与关于您的更改的任何讨论。确保清晰地表达您的想法。

一些提示#

1. 您的 Notebook 应该是一个 `.md` 文件。#

您的 Notebook 应该采用 MyST markdown 格式（参见：https://myst-parser.readthedocs.io/en/latest/index.html）。

如果您通常使用 .ipynb Notebook 进行工作，可以使用以下 jupytext 命令将其转换为 .md

jupytext  --to md:myst <notebook-name>.ipynb

2. 尽可能使用代码生成的图像。#

展示如何创建高质量的图/网络数据可视化是 nx-guides 教程的主要目标之一！因此，应尽可能在 Notebook 中直接通过代码生成图像（尤其是图可视化）。

如果您也想在 Notebook 中包含静态图像，您可以

3. 将依赖项添加到 `requirements.txt`#

如果您想安装和使用其他库，请将相关的依赖项添加到 nx-guides 仓库下的 requirements.txt 中。（即，不要在您的 Notebook 中使用 pip install 命令安装依赖项。）

4. 尚不支持用户输入。#

我们的 Notebook 尚不支持从读者处获取输入。尽管这是一个我们将来会考虑的想法，但目前请保持 Notebook 的叙述性。

5. 不要忘记将您的 Notebook 路径添加到 `index.md`。#

您应该将您的 Notebook 路径包含在 nx-guides/content/algorithms 目录下的 index.md 文件中。

6. 标题级别#

标题级别应逐级递增。例如，如果您从 2 级标题跳到 4 级标题，msyt 将报错，阻止您通过测试。在本例中，如果当前标题级别是 2，则后续标题级别需要是 2 或 3。

7. 您无需完全按照 NetworkX 内部的方式实现算法。#

nx-guides 为 NetworkX 算法提供了教学资源。为此，您不必包含 NetworkX 中算法的源代码。如果可能，请随意删除您认为可以更好地精简的部分 :)

8. 随意使用真实世界数据集#

nx-guides Notebook 的目标之一是使用不同的算法探索和分析真实世界数据集。如果您认为它们有用，请随意使用。

这里有一个很好的数据集来源

http://snap.stanford.edu/data/index.html

9. 如果测试仍然失败怎么办？#

所有测试完成后，您可以看到阻止您的 PR 通过测试的警告和错误。为此，请转到您的 PR 的“对话”页面底部。在“ci/circleci: build-docs”测试套件左侧会显示红色交叉标志。点击右侧的“详细信息”链接查看错误和警告。

您还可以点击“ci/circleci: build-docs artifact”右侧的“详细信息”链接。如果您的 Notebook 已构建，这将带您查看项目的完整文档，就像该分支已合并一样。然后您可以导航到您创建的 Notebook 并检查您的文档是否看起来良好。

环境#

编辑您的 markdown 文件的一个好方法是使用 Jupyter Notebook 或其他 markdown 文件编辑器。只需确保元数据与其他 nx-guides 中的 markdown 文件相符即可。

格式指南#

编写一个清晰的标题。
在介绍您的主题时，请说明您正在解决的问题以及您正在使用 NetworkX 的哪个部分。
在您的介绍后，在 Notebook 的顶部包含一个“导入包”部分。在您的介绍下方的代码单元格中添加所有包的导入语句（参见其他 Notebook 获取示例）
对代码进行大量注释，尤其是令人困惑的部分。
引用所有来源。在文档底部包含文内引用和参考文献部分。有关如何编写这些引用和引用的示例，请参阅其他 Notebook

贡献者指南

目录