如何贡献

作者: Nicolas Rougier

确保阅读此 文档风格指南 [1] 以及这些关于文档内容和工作流程的 提示、技巧 [2] 和约定。

如何贡献？

  • 如果你发现讲座中的错别字、不清楚或笨拙的措辞，请帮助改进它们。 可以通过 编辑你 GitHub 分支上的讲座文件 来进行简单的文本编辑。 在讲座的每个 html 页面上，右上角的 编辑 按钮链接到该页面的可编辑源代码（你仍然需要创建项目的 fork）。 编辑源代码并选择“为此提交创建一个新分支并启动一个拉取请求”。

  • 选择一个尚未涵盖的主题并撰写！

    首先在 GitHub 上创建一个新问题，解释你想要涵盖的主题，以便与编辑和贡献者讨论未来教程的范围。

    然后在其中一个章节目录（intro、advanced 或 packages）中创建一个新目录，并为新的教程创建一个名为 index.rst 的文件。 将新文件添加到相应章节的目录中（在它的 index.rst 中）。

请记住，教程要在不同的地方教授，不同的部分可以组合成一个关于科学计算的 Python 课程。 因此，你需要让它们具有交互性和合理的时间长度（一到两个小时）。

最后但并非最不重要的一点是，此材料的目标是提供简明扼要的文本，以学习科学 Python 生态系统的核心功能。 如果你想为参考材料贡献力量，我们建议你为感兴趣的特定包的文档做出贡献。

使用 GitHub

创建自己的教学材料版本的最简单方法是在 GitHub 上进行 fork，并使用 git 版本控制系统来维护自己的 fork。 为此，你只需要在 GitHub 上创建一个帐户，并点击 此页面 右上角的 fork 按钮。 你可以使用 git 从你的 fork 中拉取，并将更改推回它。 如果你想将更改贡献回来，只需填写一个 pull request，使用你 fork 页面顶部的按钮。

网上有许多资源可以学习 git 和 GitHub，比如 https://try.github.io 适合初学者。

请不要修改 Makefile，除非绝对必要。

保持简洁：折叠段落

HTML 输出用于在教学过程中在屏幕上显示。 目标是在讲义中显示相同的材料。 因此需要非常简洁的显示，使用项目符号列表而不是完整的段落和句子。 对于人们可以阅读和参考的更详细的讨论，请使用 tip sphinx 指令。 它创建可折叠的段落，这些段落可以在口头演示中隐藏起来

.. tip::



    Here insert a full-blown discussion, that will be collapsible in

    the HTML version.



    It can span on multiple paragraphs

这将呈现为

提示

在这里插入完整的讨论，它将在 HTML 版本中可折叠。

它可以跨越多个段落

图形和代码示例

我们不检查存储库中的图形。 任何图形都必须从一个 python 脚本生成，该脚本需要命名为 plot_xxx.py（xxx 可以是任何东西）并放入 examples 目录中。 生成的图像将根据脚本名称命名。

../_images/sphx_glr_plot_simple_001.png

这是包含你的图像并将其链接到代码的方法

.. image::  auto_examples/images/sphx_glr_plot_simple_001.png

  :target: auto_examples/plot_simple.html

你可以使用 literal-include 指令显示相应的代码。

"""

A simple example

=================



"""



import numpy as np

import matplotlib.pyplot as plt



X = np.linspace(-np.pi, np.pi, 100)

Y = np.sin(X)



plt.plot(X, Y, linewidth=2)

plt.show()

注意

Python 脚本到图形和示例库的转换由 sphinx-gallery 包提供。

使用标记

应该使用三种主要类型的标记：斜体、粗体 和 等宽字体。 斜体 应该用于介绍新的技术术语，粗体 应该用于强调，等宽字体 用于源代码。

在结构化文本标记中，这是

when using *object-oriented programming* in Python you **must** use the

``class`` keyword to define your *classes*.

链接到包文档

科学 Python 讲座的目标不是复制或替换各种包的文档。 你应该尽可能地链接到原始文档。

对于交叉引用 API 文档，我们更喜欢使用 intersphinx 扩展。 这提供了 :mod:、:class: 和 :func: 指令，分别用于交叉链接到模块、类和函数。 例如，:func:`numpy.var` 将创建一个类似于 numpy.var() 的链接。

章节、部分、小节、段落

尽量避免低于段落粒度，否则你的文档可能难以阅读

=============

Chapter title

=============



Sample content.



Section

=======



Subsection

----------



Paragraph

.........



And some text.

警示

注意

这是一个注意

警告

这是一个警告

清除浮动

使用 :align: right 定位的图形是浮动的。 要将其刷新，请使用

|clear-floats|

参考文献