这项工作由 Anaconda Inc 提供支持

摘要

我们最近改变了组织和连接 Dask 文档的方式。我们的方法可能对其他将文档分散到许多不同构建和站点的伞形项目有用。

Dask 将文档拆分成许多页面

Dask 的文档被拆分成几个不同的网站，每个网站由不同的团队管理，负责不同的子项目

1. dask.pydata.org : 主站点
2. distributed.readthedocs.org : 分布式调度器
3. dask-ml.readthedocs.io : 面向机器学习的 Dask
4. dask-kubernetes.readthedocs.io : 在 Kubernetes 上的 Dask
5. dask-jobqueue.readthedocs.io : 在 HPC 系统上的 Dask
6. dask-yarn.readthedocs.io : 在 Hadoop 系统上的 Dask
7. dask-examples.readthedocs.io : 使用 Dask 的示例
8. matthewrocklin.com/blog,jcrist.github.io,tomaugspurger.github.io,martindurant.github.io/blog :开发者个人博客

这种文档拆分与开发团队的拆分相匹配。每个子项目的团队以自己的方式管理自己的文档。他们以自己的节奏发布，并自行决定技术选择。这使得开发人员在开发和更改软件库时更有可能维护文档。

我们使文档编写变得容易。这种选择导致许多不同的文档系统出现。

这种方法很常见。搜索 Jupyter 文档会得到以下列表

• jupyter.readthedocs.io/en/latest/
• jupyter-notebook.readthedocs.io/en/stable/
• jupyter.org/
• jupyterhub.readthedocs.io/en/stable/
• nteract.io/
• ipython.org/

不同的团队半独立开发，创建了不同的网页。这是不可避免的。要求一个大型分布式团队协调创建一个统一的网站会增加巨大的摩擦，从而导致文档覆盖范围变差。

问题

然而，虽然使用独立的网站带来了出色的覆盖范围，但也导致文档碎片化。这使得用户更难在站点之间平滑导航并发现适当的内容。

整体式文档对读者友好，模块化文档对作者友好。

我们的解决方案

上个月，我们采取了一些措施来连接我们的文档，使其更具凝聚力，同时仍允许独立开发。本文概述了以下步骤

1. 组织在单个域名 dask.org 下
2. 开发一个 Sphinx 模板项目以实现统一风格
3. 除了项目内部的目录外，还包含一个跨项目导航栏

我们在此过程中还做了其他一些我们认为有用的事情，但这可能更具体地与 Dask 相关。

1. 我们将此博客移至 blog.dask.org
2. 我们改进了示例笔记本，使其既可以托管静态站点，也可以托管实时 Binder

1：组织在单个域名 Dask.org 下

此前，我们的一些文档位于 readthedocs 下，一些位于 dask.pydata.org 子域名下（感谢 NumFOCUS！），还有一些页面位于个人网站上，例如matthewrocklin.com/blog。

在寻找新的 dask 域名来托管我们所有内容时，我们注意到dask.org 重定向到了anaconda.org，并且很高兴得知 Anaconda Inc 的某人有先见之明，早早注册了这个域名。

Anaconda 很高兴将域名所有权转让给 NumFOCUS，他们现在帮助我们维护它。现在，我们所有的文档都以子域名的形式在该单个域名下可用

• dask.org
• docs.dask.org
• distributed.dask.org
• ml.dask.org
• kubernetes.dask.org
• yarn.dask.org
• jobqueue.dask.org
• examples.dask.org
• stories.dask.org
• blog.dask.org

这种统一性意味着您想要的内容可能就在 that-thing.dask.org 上，这比其他方式更容易猜测。

非常感谢 Andy Terrel 和 Tom Augspurger 管理此次迁移，以及 Anaconda慷慨捐赠域名。

2：跨项目导航栏

我们希望读者能够快速发现其他可用的站点。我们所有的站点都有侧边导航栏，帮助读者在特定站点内导航，但现在它们也有顶部导航栏，帮助他们在项目之间导航。

此导航栏在我们新的 Sphinx 主题中独立于所有文档项目进行管理。

3：Dask Sphinx 主题

为了提供统一的风格感，我们开发了自己的 Sphinx HTML 主题。它继承了 ReadTheDocs 的主题，但更改了样式以匹配 Dask 的颜色和视觉风格。我们将此主题作为一个 PyPI 包发布，所有项目的 Sphinx 构建都可以导入和使用它（如果需要）。我们可以在这个包中更改样式并发布到 PyPI，所有项目在下一次构建时都会获取这些更改，而无需将样式表复制到不同的仓库中。

这使得多个不同项目可以分别演进内容（他们关心的部分）和构建过程，而与样式无关（他们通常不太关心）。我们有一个单一的样式表，可以在任何地方轻松使用。

4：将 Dask 博客移至 blog.dask.org

此前，大多数关于 Dask 的公告都是由维护者之一的个人博客撰写和发布的。这使得项目信息分散，人们难以发现好的内容。社区成员也没有好的方法来建议博客分发给更广泛的社区，除非他们自己开始写。

现在我们在 blog.dask.org 上有一个官方博客，它提供提交到github.com/dask/dask-blog 的文件。这些文章是简单的 Markdown 文件，人们应该很容易生成。例如，本文的源文件可在github.com/dask/dask-blog/blob/gh-pages/_posts/2018-09-27-docs-refactor.md 获取

我们鼓励社区成员通过向该仓库提交拉取请求来分享他们使用 Dask 完成的工作的帖子。

5：将示例托管为静态 HTML 和实时 Binder 会话

Dask 社区维护了一系列示例笔记本，展示了如何以各种方式使用 Dask。这些笔记本位于github.com/dask/dask-examples，用户可以轻松下载和运行。

为了从这些笔记本中获得更多价值，我们现在以两种额外的方式展示它们

1. 作为静态 HTML 托管在 examples.dask.org，使用 nbsphinx 插件渲染。
2. 静态渲染并能够快速在它们之间导航，极大地增加了探索它们的乐趣。我们希望这能鼓励用户更广泛地探索。
5. 作为使用 mybinder.org 在云上运行的实时笔记本。您可以点击此按钮体验任何这些笔记本

1. .
3. 这让人们可以更深入地探索。此外，由于我们将 Dask JupyterLab 扩展连接到此环境，用户可以立即直观地体验并行计算的感觉（如果您在计算过程中没有使用过 dask dashboard，您真的应该试试那个链接）。

现在这些示例获得了更多的曝光，我们希望这能鼓励社区成员提交新的示例。我们希望通过提供基础设施，吸引更多内容创作者的加入。

我们也鼓励其他项目参考我们在github.com/dask/dask-examples 中所做的工作。我们认为这种模式可能对其他项目具有广泛的用途。

结论

感谢您的阅读。我们希望这篇文章能促使读者重新探索 Dask 的文档，并促使开发者考虑将上述一些方法应用于自己的项目。