文档编写#
Bokeh 文档是整个 Bokeh 社区的重要资源。它帮助指导新用户，并且是经验丰富的用户和开发人员的权威参考。这就是为什么对 Bokeh 的所有贡献都必须包含充分的文档。这也是我们制定标准以确保 Bokeh 的文档始终易于访问且保持更新的原因。
就像 Bokeh 本身一样，文档是社区共同努力的成果。并且就像 Bokeh 一样，文档也在不断地调整和改进。事实上，帮助完善文档是为 Bokeh 做出贡献最有价值的方式之一。这也是一个很好的入门方式，并能让你作为新的贡献者进行自我介绍。
本节介绍了 Bokeh 的 文档风格指南，用于为文档做出贡献。本节还包括有关如何在本地开发环境中 构建 和 编辑 文档的详细信息。
从哪里开始#
开始为 Bokeh 文档做贡献的一个简单方法是提交 pull request，以修复你在 Bokeh 文档中可能发现的任何错别字或其他小错误。这总是非常受欢迎的！
除了快速修复之外，还可以查看 GitHub 上 未解决的文档 issue 列表。此列表包含多个项目作为起点。
文档风格指南#
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，后者通常仅在基于 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 源代码中的 Docstring 和模型帮助文本
文档的这部分由所有 Bokeh 模块及其属性的详细解释组成。这些文本可以从 Python 解释器和大多数 Python 开发环境中获得。Sphinx 还使用这些文本来生成 Bokeh 文档的 参考指南 部分。
在文件 docs/bokeh/source/rst_epilog.txt 中，你可以找到许多在叙述性文档以及 docstring 和模型帮助文本中使用的常见替换。此文件作为 Bokeh 的 Sphinx 配置的 epilog.rst environment variable 加载。
为 Bokeh 的叙述性文档编写内容#
Bokeh 的叙述性文档由以下四个要素组成
Sphinx 从 reStructuredText (.rst) 文件生成这些要素中的每一个。要编辑其中任何一个要素，请在 Bokeh 源代码树的 docs/bokeh/source/docs 文件夹中打开相应的 ReST 源文件。
有关如何使用 reStructuredText 格式化文本的信息，请参阅 Sphinx 网站上的 reStructuredText 入门 或 官方 reStructuredText 网站。
有关写作风格的信息，请参阅 Bokeh 的 文档风格指南 和 Google 开发者文档风格指南。
为 Bokeh 的源代码文档做贡献#
Bokeh 中的所有函数和方法都使用 docstring。此外，Bokeh 使用自己的系统来提供 有关各个属性的详细信息。
编写 docstring#
为了自动处理 Python docstring，Bokeh 使用了 Sphinx 的扩展 Napoleon，并采用了 Napoleon 的 Google 风格。为了使 Napoleon 正常工作，你编写的所有 docstring 都需要遵循 Google Python 风格指南 中的规则。
Docstring 通常包括以下三个要素
函数功能的简短描述，以动词开头。例如：“创建并返回一个新的 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.
""")