入门#

准备您的首次贡献#

  1. 我们的文档使用 reStructured Text、Markdown 和 Jupyter 笔记本。

  2. 我们广泛使用 Sphinx 来构建文档。

  3. 我们使用 Transifex 帮助将文档翻译成多种语言。

  4. 我们的文档托管在 Read the Docs 上。

开发您的贡献#

Jupyter 的文档分布在几个项目中，列在Jupyter 文档主页上。这些说明适用于所有 Jupyter 项目，尽管有些项目有进一步的贡献指南。

克隆存储库#

  1. 根据您要贡献文档的项目，在 GitHub 上 fork 相应的项目存储库。

  2. 将存储库克隆到您的系统。

编辑文档源文件#

项目的源文件通常位于项目的 docs/source 目录中。reStructured Text 文件名以 .rst 结尾，Jupyter 笔记本文件以 .ipynb 结尾。

  1. 当使用 reStructured Text 源文件时，在您喜欢的文本编辑器中对 .rst 文件进行所需的更改。

  2. 如果需要编辑笔记本文件，您需要根据安装文档安装 Jupyter 笔记本。然后，运行 Jupyter 笔记本并编辑所需的文件。在保存 Jupyter .ipynb 文件之前，请清除输出单元格。保存文件并测试您的更改。

测试更改#

应安装 Sphinx 以测试您的文档更改。为获得最佳结果，我们建议您安装稳定的开发版本 Sphinx (pip install git+https://github.com/sphinx-doc/sphinx@stable) 或当前发布的 Sphinx 版本 (pip install sphinx)。

此外，您可能需要以下软件包：sphinxcontrib-spelling、sphinx_rtd_theme、nbsphinx、pyenchant、recommonmark 0.4.0 和 jupyter_sphinx_theme，可以通过 pip install sphinxcontrib-spelling sphinx_rtd_theme nbsphinx pyenchant recommonmark==0.4.0 jupyter_sphinx_theme 安装。

如果您在 Linux 上，您可能还需要通过运行 sudo apt-get install enchant 来安装 Enchant C 库。

一旦一切都安装完毕，应从 docs 目录使用终端/命令行执行以下命令

  • make html 会构建文档的本地 html 版本。输出消息将显示错误或提供 html 文档的位置。例如，提供的位置可能是 build/html，要在浏览器中查看这些文档，请输入 open build/html/index.html。

  • make linkcheck 将检查文档中的外部链接是否有效或是否不再有效（即导致 500 未找到错误）。

注意：我们建议使用 Python 3.4+ 来构建文档。如果您正在编辑文档，可以使用 Python 2.7.9+ 或 Github 编辑器。

创建拉取请求#

一旦您对更改感到满意，请按照上述说明提交 GitHub 拉取请求。如果文档更改与开放的 GitHub issue 相关，请在拉取请求消息中提及 issue 编号。

项目审阅者将查看您的更改并提供反馈或将您的更改合并到文档中。

提问#

请随时在 Jupyter 的 Google Group 或 GitHub 上的开放 issue 中提问。