文档¶

只有在提供足够和适当的文件支持的情况下，才会接受对博凯的捐款。本节概述如何在本地构建和编辑文档，并描述项目遵循的约定。

帮助编写文档是对项目做出贡献的最有价值的方法之一。这也是一个很好的开始和介绍自己作为一个新的贡献者。解决打字错误或其他小文档错误的最有可能的方法是，发现问题的人立即向提交请求并更正。 这是永远感激的！ 除了快速修复，还有一个列表 Open Docs Issues 任何人都可以在GitHub上查看需要帮助的任务。

处理文档¶

Sphinx 用于生成HTML文档。由于Bokeh对JavaScript的固有依赖性，官方构建配置不支持其他输出格式。本节介绍如何使用Sphinx从源代码构建Bokeh文档。

安装要求¶

为了从源代码构建文档，建议您首先按照中的说明进行操作正在设置 .

文档中的一些Bokeh示例所依赖的示例数据由于其大小而未包含在bokehgithub存储库或发布的包中。

安装Bokeh之后，可以通过在Bash或Windows提示符下执行以下命令来获取示例数据：

bokeh sampledata

见样本数据有关如何下载示例数据的其他说明。

构建文档¶

要生成完整的文档，请首先导航到 sphinx Bokeh源目录树的子目录。

cd sphinx

狮身人面像使用 make 控制生成过程的工具。Bokeh makefile最常见的目标是：

clean: 删除所有以前生成的文档输出。所有输出将在下一个构建中从头生成。
html: 生成任何未生成或需要重新生成的HTML输出（例如，因为自上次生成以来输入源文件已更改）。
serve: 启动一个服务器来为文档提供服务，并打开一个web浏览器来显示它们。请注意，由于涉及到JavaScript文件，因此需要启动一个真正的服务器来完整地查看文档的许多部分。

例如，要清除docs build目录，请在命令行运行以下命令：

make clean

多个目标可以合并成一个 make 调用。例如，执行以下命令将清除文档生成，从头生成所有HTML文档，然后打开浏览器显示结果：

make clean html serve

默认情况下，构建的文档将从CDN加载最新的bokehj。如果要对BokehJS进行本地更改，并希望文档使用本地构建的BokehJS，则可以设置环境变量 BOKEH_DOCS_CDN 打电话之前 make ：

BOKEH_DOCS_CDN=local make clean html serve

构建文档还需要设置 GOOGLE_API_KEY 环境变量 gmap 绘图使用。你可以 create a new API Key . 或者如果你不在乎 gmap 绘图有效，您可以在调用之前使用假值设置变量 make ：

GOOGLE_API_KEY=foo make clean html serve

源代码文档¶

Docstrings和模型帮助可以从Python解释器获得，但是Sphinx构建也可以自动生成一个完整的参考文献 .

Bokeh使用一些常见的约定来创建一致的文档样式。

文档字符串¶

我们使用 Sphinx Napoleon 为我们的参考文档处理docstring。

所有docstring都是 Google Style Docstrings . Docstrings通常应该以一个动词开头，在一个简短的语句中说明函数或方法的作用。例如，首选“动词优先”样式：

""" Create and return a new Foo. (GOOD)

"""

在下面更详细的句子中：

""" This function creates and returns a new Foo. (BAD)

"""

doc的字符串和函数通常应包括以下部分：

Args （除非函数不带参数）
Returns （即使函数只返回 None ）

对参数的简短描述应该这样写，插入一个隐含的“IS”就构成了一个完整的句子。例如：

title_font (str, optional) :
    A font used for the plot title (default: Sans)

可以合理地理解为“标题字体是用于绘图标题的字体”。

一个完整的例子可能如下：

def somefunc(name, level):
    ''' Create and return 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 属性类型的参数，在生成引用文档时，该类型被解释为标准Sphinx 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.
    """)

叙述性文件¶

叙述性文档包括所有不是从docstrings和Bokeh属性helpstrings自动生成的文档。这包括用户指南、快速入门等。这些文档的源代码是位于 sphinx/source/docs 源树的子目录。

章节标题¶

在叙述性文档中，标题帮助用户遵循要点和章节。以下概述了标题层次结构：

Top level
=========

This will add a "Top Level" entry in the navigation sidebar.

Second level
------------

This may add a sub-entry in the sidebar, depending on configuration.

Third level
~~~~~~~~~~~

Fourth level
''''''''''''

注意下划线的长度 must 匹配标题文本，否则Sphinx构建将失败。

发行说明¶

每个版本都应该在下面添加一个新文件 sphinx/source/docs/releases 这简要描述了版本中的更改，包括任何迁移注释。文件名应为 <version>.rst ，例如 sphinx/source/docs/releases/0.12.7.rst . Sphinx构建将自动将此内容添加到所有版本的列表中。