重构文档

这项工作由 Anaconda Inc 支持

摘要

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

Dask 将文档拆分成许多页面

Dask 的文档被拆分为几个不同的网站，每个网站由不同的团队管理，对应不同的子项目

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

这种文档拆分与开发团队的拆分相符。每个子项目团队以自己的方式管理自己的文档。他们按照自己的步调发布，并对技术做出自己的决定。这使得开发者在开发和更改软件库时更有可能维护文档。

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

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

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

问题

然而，虽然使用独立的网站能够实现出色的覆盖范围，但它也使得文档变得零散。这使得用户更难在不同站点之间顺畅地导航并发现合适的内容。

一体式文档对读者有利，模块化文档对作者有利。

我们的解决方案

在过去的一个月里，我们采取了一些措施来连接我们的文档，使其更具凝聚力，同时仍然支持独立开发。这篇文章概述了以下步骤

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

我们在此过程中还做了一些我们认为有用的事情，但这些事情可能更特定于 Dask。

我们将此博客移至 blog.dask.org
我们改进了示例 Notebook，使其既能托管静态站点，也能托管实时 Binder

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

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

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

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

这种统一性意味着您想要的东西很可能位于 that-thing.dask.org，这比其他方式更容易猜测。

非常感谢 Andy Terrel 和 Tom Augspurger 管理此次迁移，并感谢 Anaconda 大方捐赠域名。

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

adding a navbar to dask docs

此导航栏在我们的新 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 社区维护了一系列示例 Notebook，展示了如何以多种方式使用 Dask。这些 Notebook 位于 github.com/dask/dask-examples，用户可以轻松下载和运行。

为了从这些 Notebook 中获得更多价值，我们现在通过另外两种方式展示它们

作为 examples.dask.org 上的静态 HTML，使用 nbsphinx 插件渲染。

看到它们以静态方式渲染并能够快速在其间导航，确实大大增加了探索的乐趣。我们希望这能鼓励用户更广泛地探索。
作为使用 mybinder.org 在云上运行的实时 Notebook。点击此按钮即可试用这些 Notebook：。

这使得人们能够更深入地探索。此外，由于我们将 Dask JupyterLab 扩展连接到此环境，用户可以立即直观地体验并行计算的感觉（如果您在计算期间未使用过 Dask 仪表盘，强烈建议您尝试一下那个链接）。

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

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

结论

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

博客评论由 Disqus 提供支持

摘要