入门#
准备您的首次贡献#
我们的文档使用 reStructured Text、Markdown 和 Jupyter 笔记本。
我们广泛使用 Sphinx 来构建文档。
我们使用 Transifex 帮助将文档翻译成多种语言。
我们的文档托管在 Read the Docs 上。
开发您的贡献#
Jupyter 的文档分布在几个项目中,列在Jupyter 文档主页上。这些说明适用于所有 Jupyter 项目,尽管有些项目有进一步的贡献指南。
克隆存储库#
根据您要贡献文档的项目,在 GitHub 上 fork 相应的项目存储库。
将存储库克隆到您的系统。
编辑文档源文件#
项目的源文件通常位于项目的 docs/source
目录中。reStructured Text 文件名以 .rst
结尾,Jupyter 笔记本文件以 .ipynb
结尾。
当使用 reStructured Text 源文件时,在您喜欢的文本编辑器中对
.rst
文件进行所需的更改。如果需要编辑笔记本文件,您需要根据安装文档安装 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 中提问。