贡献者指南#

首次贡献者简明路线图#

nx-guides 的目标是提供关于图论、网络分析以及 NetworkX 实现（算法等）的教学笔记本。这是开始参与开源贡献的绝佳场所！

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

将 nx-guides 仓库克隆到你的本地机器。
将你的 Markdown 笔记本添加到适当的文件夹中（例如，如果你添加一个新算法，请在 nx-guides/content/algorithms 中创建一个以其名称命名的文件夹，并遵循其他算法的结构）。
确保你的笔记本符合本文档中的格式指南。
使用子目录存放图片和数据。如果你使用了任何静态图片和数据，请将它们放在相应的文件夹下。（可选）
将你的笔记本路径添加到 index.md 文件中。
当你完成工作并感觉准备就绪时，将你的更改推送到仓库并开启一个 PR 进行审查。
参与有关你的更改的任何讨论。确保清晰地表达你的想法。

一些提示#

1. 你的笔记本应为 `.md` 文件。#

你的笔记本应采用 MyST Markdown 格式（参见：https://myst-parser.readthedocs.io/en/latest/index.html）。

如果你通常使用 .ipynb 笔记本进行工作，可以使用以下 jupytext 命令将其转换为 .md 格式：

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

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

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

如果你也倾向于在笔记本中包含静态图像，

3. 将需求添加到 `requirements.txt` 中。#

如果你倾向于安装和使用其他库，请将相关需求添加到 nx-guides 仓库下的 requirements.txt 中。（例如，不要在笔记本中使用 pip install 命令安装需求。）

4. 目前不支持用户输入。#

我们的笔记本目前还不支持从读者那里获取输入。尽管我们考虑在未来实现这一点，但目前请保持叙述性笔记本。

5. 不要忘记将你的笔记本路径添加到 `index.md` 中。#

你应该在 nx-guides/content/algorithms 下的 index.md 文件中包含你的笔记本路径。

6. 标题级别#

标题级别应逐级递增。例如，如果你从二级标题跳到四级标题，msyt 将产生错误以防止你通过测试。在这个例子中，如果当前标题级别是 2，下一个标题级别需要是 2 或 3。

7. 你不需要以与 NetworkX 内部完全相同的方式实现算法。#

nx-guides 为 NetworkX 算法提供了一个教学资源。因此，你不必包含与 NetworkX 中完全相同的算法源代码。如果可能，可以自由地删除你认为可以更好地压缩的部分 :)

8. 欢迎使用真实世界的数据集#

nx-guides 笔记本的一个目标是使用不同的算法来探索和分析真实世界的数据集。如果你认为有用，欢迎使用它们。

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

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

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

一旦所有测试完成，你可以看到阻止你的 PR 通过测试的警告和错误。为此，请转到你的 PR 中“Conversation”页面的底部。在“ci/circleci: build-docs”测试套件的左侧会有红色的叉号。点击右侧的“Details”链接以查看错误和警告。

你也可以点击“ci/circleci: build-docs artifact”右侧的“Details”链接。如果你的笔记本已构建，这将带你进入项目的完整文档，就像这个分支已被合并一样。然后你可以导航到你创建的笔记本，检查你的文档是否看起来良好。

环境#

编辑 Markdown 文件的一个好方法是使用 Jupyter Notebook 或其他 Markdown 文件编辑器。只需确保元数据与其他 Markdown 文件在 nx-guides 中的元数据一致。

格式指南#

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

贡献者指南

Contents