编写文档

Bokeh文档是整个Bokeh社区的重要资源。它帮助指导新用户，并且是经验丰富的用户和开发人员的权威参考。这就是为什么所有对Bokeh的贡献都必须包含足够的文档。这也是为什么我们设定了标准，以确保Bokeh的文档保持易于访问和最新。

就像Bokeh本身一样，文档也是社区共同努力的结果。而且就像Bokeh一样，文档也在不断地被调整和改进。事实上，帮助编写文档是为Bokeh做出贡献的最有价值的方式之一。这也是一个很好的开始方式，并作为新贡献者介绍自己。

本节描述了Bokeh的 文档风格指南 ，用于贡献文档。本节还包括了如何在本地开发环境中 构建 和 编辑 文档的详细信息。

从哪里开始

开始为Bokeh文档做出贡献的一个简单方法是提交拉取请求，针对你在Bokeh文档中发现的任何拼写错误或其他小错误。这总是受到欢迎的！

除了快速修复外，还可以查看GitHub上的开放文档问题列表。该列表包含几个项目作为起点。

文档风格指南

Bokeh的文档使用了Google开发者文档风格指南。

如果您的贡献包括大量编辑或添加，请熟悉Google的风格指南。一个简单的入门方法是使用Google的免费技术写作课程。

注意

你会发现Bokeh的文档中有许多部分尚未遵循这些风格指南。我们目前正在努力实施这些更改。然而，我们要求所有文档贡献都遵循本文档中描述的标准。

良好风格的原则

在您为Bokeh编写的所有内容中，请遵循以下基本准则：

• 注意句子长度。尽量避免需要超过两个逗号的句子。考虑将较长的句子拆分开。你也可以使用项目符号或编号列表来代替。

• 避免使用行话或不常见的词语和短语。请记住，许多Bokeh的用户并不以英语为主要语言。

• 尽可能使用主动语态而不是被动语态。

• 以第二人称（‘你’）称呼读者。避免使用第一人称（‘我们’）或第三人称（‘用户’）。

• 使用美式英语拼写和语法（请参考Merriam-Webster以确保拼写一致）。

• 使用标题的句子大小写（像在普通句子中一样大写单词，但不要在末尾使用任何标点符号）。

• 使用序列逗号，也称为牛津逗号。

• 以包容和可访问的方式编写。

• 在您的开发环境中使用拼写检查器。

请参考Google开发者文档风格指南以获取更详细的信息。

常用术语

这些是一些常用的术语和短语及其在整个叙述文档中使用的拼写：

术语	详情
Bokeh, BokehJS	始终大写 Bokeh 和 BokehJS
JavaScript	将‘J’和‘S’都大写
Jupyter 笔记本	大写Jupyter，但不大写notebook
pandas	不要大写 pandas
Python	始终将Python（语言）大写

有关Bokeh文档中使用的定义和概念，请参阅 词汇表。

一般来说，请参考Google开发者文档风格指南的词汇表。

设置和构建Bokeh的文档

Bokeh 使用 Sphinx 生成在 docs.bokeh.org 上显示的 HTML 文件。文档是用 reStructuredText (ReST) 编写的。

HTML 是 Bokeh 文档支持的唯一输出格式。许多页面使用动态内容并严重依赖 JavaScript。Bokeh 的文档还使用了多个 自定义 Sphinx 扩展。

1. 准备你的环境

要构建文档，请按照设置开发环境中的说明操作，并确保您已在控制台中激活了bkdev环境：

conda activate bkdev

除非你刚刚安装或更新了你的conda环境，你应该确保所有的包都是最新的。从你的源代码检出目录的根级别运行这个命令来更新bkdev：

conda env update --name bkdev --file <environment file> --prune

使用最初用于创建 bkdev 的环境文件。

2. 设置环境变量

为了构建文档，您必须设置 环境变量 GOOGLE_API_KEY。文档中包含一些带有地图的图表，需要一个有效的Google API密钥才能正确构建这些图表。您有两个选择：

• 按照Google开发者网站上的说明生成一个新的API密钥。

• 使用一个占位符值，如some_value，而不是有效的API密钥。如果你使用占位符，Bokeh文档中的一些地图图可能无法正确渲染，但文档的其他部分应该能够正确构建。这只会影响你的本地环境，对你可能提交到Bokeh仓库的任何更改应该没有影响。

激活您的conda环境后，使用以下命令设置环境变量：

conda env config vars set GOOGLE_API_KEY=some_value

接下来，您需要重新激活您的环境：

conda deactivate
conda activate bkdev

使用 conda env config vars set 使这个环境变量成为你的 bkdev 环境的一部分。每当你激活你的 bkdev 环境时，conda 现在会为你设置这个环境变量。

3. 构建Bokeh的文档

你可以在Bokeh源代码树的docs/bokeh/目录中找到Bokeh文档的所有源文件。

cd docs/bokeh/

Sphinx 使用标准的 Unix make 命令来控制构建过程。对于 Windows 用户，sphinx 目录中包含文件 make.bat。请使用此 Windows 批处理文件代替 make，后者通常仅在基于 Unix 的系统上可用。

在构建Bokeh的文档时，make 最常见的选项是：

• clean: 删除所有之前构建的文档输出。所有输出文件将在下一次构建时从头生成。

• html: 构建任何尚未构建或需要重新构建以包含对文档源文件更改的HTML输出。

• serve: 启动一个最小的网络服务器并打开一个网页浏览器来显示文档。启动服务器是必要的，因为文档的大部分内容需要后台的JavaScript文件。

要构建文档，请运行以下命令：

Linux/macOS

make html

Windows (PS)

.\make.bat html

Windows (CMD)

make.bat html

构建文档后，运行以下命令以启动服务器并在网页浏览器中显示文档：

Linux/macOS

make serve

Windows (PS)

.\make.bat serve

Windows (CMD)

make.bat serve

仅限Linux/macOS： 您可以在一个命令中组合多个目标（make.bat 不支持）。例如：

make clean html serve

注意

在本地环境中构建的文档默认会从Bokeh的内容分发网络（CDN）加载最新版本的BokehJS。如果你想使用本地版本的BokehJS，可以在调用make之前将环境变量BOKEH_DOCS_CDN设置为local：

Linux/macOS

BOKEH_DOCS_CDN=local make clean html serve

Windows (PS)

$Env:BOKEH_DOCS_CDN = "local"
.\make.bat html
.\make.bat serve

Windows (CMD)

set BOKEH_DOCS_CDN=local
make.bat html
make.bat serve

为了加快本地文档的构建速度，您可以选择使用一个实验性的 Sphinx 功能，该功能可以将构建过程分布在多个 CPU 和核心上。此功能仅在 Linux 和 macOS 上有效（在 Windows 上无效）。在 macOS 上，此功能仅在 Python 3.7 上有效。要使用此实验性功能，请将选项 SPHINXOPTS="-j auto" 添加到您的构建命令中：

make clean html serve SPHINXOPTS="-j auto"

要了解更多关于Sphinx构建过程的选项，请参阅Sphinx文档中的 sphinx-build。

编写Bokeh的文档

在docs.bokeh.org上可用的文档主要由以下两个元素组成：

叙述性文档

这部分文档包含类似教程的描述和Bokeh的使用说明。这包括用户指南和贡献者指南。

Bokeh的Python源代码中的文档字符串和模型帮助文本

这部分文档包含了对所有Bokeh模块及其属性的详细解释。这些文本可以从Python解释器和大多数Python开发环境中获取。Sphinx也使用这些文本来生成Bokeh文档的参考指南部分。

在文件 docs/bokeh/source/rst_epilog.txt 中，你可以找到许多在叙述文档、文档字符串和模型帮助文本中使用的常见替换。该文件作为 Bokeh 的 Sphinx 配置的 epilog.rst environment variable 被加载。

为Bokeh的叙述文档编写

Bokeh的叙述文档由以下四个元素组成：

• First steps: 入门指南和安装说明

• User guide: 使用Bokeh的描述和说明

• Gallery: 带有源代码的交互式示例

• Contributor guide: 为Bokeh贡献的指南

Sphinx 从 reStructuredText (.rst) 文件生成每个这些元素。要编辑任何这些元素，请在 Bokeh 源代码树的 docs/bokeh/source/docs 文件夹中打开相应的 ReST 源文件。

有关如何使用reStructuredText格式化文本的信息，请参阅 Sphinx网站上的reStructuredText入门指南 或官方的reStructuredText网站。

有关写作风格的信息，请参阅Bokeh的 文档风格指南 和Google开发者文档风格指南。

为Bokeh的源代码文档做出贡献

Bokeh中的所有函数和方法都使用 docstrings。此外，Bokeh使用自己的系统来提供 关于各个属性的详细信息。

编写文档字符串

为了自动处理Python文档字符串，Bokeh使用了一个名为Napoleon的Sphinx扩展，并采用了Napoleon的Google风格。为了使Napoleon正常工作，您编写的所有文档字符串都需要遵循Google Python风格指南中的规则。

文档字符串通常包括以下三个元素：

• 函数功能的简短描述，以动词开头。例如：“创建并返回一个新的Foo。”

• 参数：列出所有参数（如果有的话）。

• 返回：描述函数的返回值，即使函数返回 None。

例如：

def foo_function(name, level):
    ''' Creates and returns a new Foo.

    Args:
        name (str) :
            A name for the Foo

        level (int) :
            A level for the Foo to be configured for

    Returns:
        Foo
    '''

编写模型和属性帮助

Bokeh的模型使用了一个自定义系统，直接在源代码中提供关于各个属性的文档。你可以通过包含一个help参数来向任何属性类型添加这种文本。

任何作为help参数传递的字符串都可以使用 reStructuredText (ReST)进行格式化。

例如：

class DataRange(Range):
    ''' A base class for all data range types.

    '''

    names = List(String, help="""
    A list of names to query for. If set, only renderers that
    have a matching value for their ``name`` attribute will be used
    for autoranging.
    """)

    renderers = List(Instance(Renderer), help="""
    An explicit list of renderers to autorange against. If unset,
    defaults to all renderers on a plot.
    """)

注意

发布说明通常由Bokeh核心团队作为Bokeh的发布管理的一部分处理。每个版本应在docs/bokeh/source/docs/releases下添加一个新文件，简要描述版本中的更改，包括任何迁移说明。文件名应为.rst，例如docs/bokeh/source/docs/releases/0.12.7.rst。Sphinx构建将自动将此内容添加到所有版本的列表中。