编写文档#
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 notebook |
将 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，make 通常仅在基于 Unix 的系统上可用。
构建 Bokeh 文档时，make 的最常见选项是
clean：删除所有先前构建的文档输出。所有输出文件将在下次构建时从头开始生成。html：构建尚未构建或需要重新构建以包含文档源文件更改的任何 HTML 输出。serve：启动一个最小的 Web 服务器并打开一个 Web 浏览器以显示文档。启动服务器是必要的，因为文档的大部分内容需要后台的 JavaScript 文件。
要构建文档，请运行以下命令
make html
.\make.bat html
make.bat html
构建文档后，运行以下命令以启动服务器并在 Web 浏览器中显示文档
make serve
.\make.bat serve
make.bat serve
仅限 Linux/macOS：您可以在一个命令中组合多个目标（make.bat 不支持）。例如
make clean html serve
注意
您在本地环境中自己构建的文档默认情况下会从 Bokeh 的内容交付网络 (CDN) 加载 BokehJS 的最新版本。如果您想改为使用您本地的 BokehJS 版本，请在调用 make 之前将 环境变量 BOKEH_DOCS_CDN 设置为 local
BOKEH_DOCS_CDN=local make clean html serve
$Env:BOKEH_DOCS_CDN = "local"
.\make.bat html
.\make.bat serve
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 Python 源代码中的文档字符串和模型帮助文本
这部分文档包含所有 Bokeh 模块及其属性的详细说明。这些文本可从 Python 解释器和大多数 Python 开发环境中获得。Sphinx 也使用这些文本生成 Bokeh 文档的参考指南 部分。
在文件docs/bokeh/source/rst_epilog.txt 中，您可以找到在叙事文档以及文档字符串和模型帮助文本中使用的许多常用替换。此文件作为 Bokeh 的 Sphinx 配置的epilog.rst 环境 变量 加载。
为 Bokeh 的叙事文档撰写#
Bokeh 的叙事文档包含以下四个要素
Sphinx 从 reStructuredText (.rst) 文件生成每个要素。要编辑任何这些要素，请在 Bokeh 源代码树的docs/bokeh/source/docs 文件夹中打开相应的 ReST 源文件。
有关如何使用 reStructuredText 格式化文本的信息，请参阅Sphinx 网站上的 reStructuredText 入门指南 或官方 reStructuredText 网站。
有关写作风格的信息，请参阅 Bokeh 的文档风格指南 和Google 开发者文档风格指南。
参与 Bokeh 源代码文档的贡献#
Bokeh 中的所有函数和方法都使用文档字符串。此外，Bokeh 使用其自身系统提供有关各个属性的详细信息。
编写文档字符串#
为了自动处理 Python 文档字符串，Bokeh 使用了一个名为Napoleon 的 Sphinx 扩展，并使用Napoleon 的 Google 风格。为了使 Napoleon 正确工作，您编写的全部文档字符串都需要遵循Google Python 风格指南 中的规则。
文档字符串通常包含以下三个要素
对函数作用的简短描述，以动词开头。例如：“创建并返回一个新的 Foo。”
Args：列出所有参数（如果有）。
Returns：描述函数的返回值，即使函数返回
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.
""")