bokeh.sphinxext¶

为了帮助自动化和简化Bokeh文档的生成，已经创建了几个Sphinx扩展。其中大多数不会引起公众的兴趣，除了 bokeh.sphinxext.bokeh_plot ，任何人都可以在自己的Sphinx文档中直接包含和嵌入bokeh图。

bokeh_autodoc¶

将Bokeh扩展集成到Sphinx autodoc中。

确保autodoc指令，例如 autoclass 在适当的情况下自动使用KEH指令。配置了以下Bokeh扩展：

bokeh_color
bokeh_enum
bokeh_model
bokeh_prop

bokeh_color¶

文档Bokeh命名为colors。

这个 bokeh-color 指令接受命名颜色作为其参数：

.. bokeh-color:: aliceblue

并生成带标签的色样作为输出。

aliceblue

这个 bokeh-color 方向可以显式使用，但也可以与 bokeh_autodoc 延伸。

bokeh_enum¶

彻底记录Bokeh枚举

这个 bokeh-enum 指令为枚举生成有用的文档，包括所有允许的值。如果值的数目很大，则完整列表将放在可折叠的代码块中。

此指令以Bokeh enum变量的名称作为参数，模块名称作为选项。可选说明可以添加为内容：

.. bokeh-enum:: baz
    :module: bokeh.sphinxext.sample

    Specify a baz style

实际案例

上述指令将生成以下输出：

baz = Enumeration(a, b, c)¶

指定样式

虽然 bokeh-enum 可以显式使用，它通常与 bokeh_autodoc 分机。以上输出将一起直接从以下代码生成：

#: Specify a baz style
baz = enumeration("a", "b", "c")

bokeh_gallery¶

从配置文件生成Bokeh图库。

bokeh_github¶

简化到BokehGithub资源的链接。

本模块证明了四个新角色，可用于轻松链接到Bokeh Github存储库中的各种资源：

:bokeh-commit: ：链接到特定提交

:bokeh-issue: ：链接到问题

:bokeh-pull: ：链接到拉取请求

:bokeh-tree: ：（版本控制）指向源树URL的链接

实际案例

以下代码：

The repo history shows that :bokeh-commit:`bf19bcb` was made in
in :bokeh-pull:`1698`, which closed :bokeh-issue:`1694`. This included
updating all of the files in the :bokeh-tree:`examples` subdirectory.

产生输出：

回购历史表明 commit bf19bcb 是在年制造的 pull request 1698 ，关闭了 #1694 . 这包括更新 examples 子目录。

bokeh_jinja¶

自动记录Bokeh Jinja2模板。

此指令获取定义Jinja2模板的属性名的模块路径：

.. bokeh-jinja:: bokeh.core.templates.FILE

任何模板参数都将显示，模板源代码将呈现在可折叠的代码块中。例如，上面的用法将生成以下输出：

FILE = <Template 'file.html'>

将Bokeh模型呈现为basic.html文件。

参数

title (str) -- 价值观 <title> 标签
plot_resources (str) -- 通常是资源的输出
plot_script (str) -- 通常是打印脚本的输出

用户可以通过提供自己接受这些相同参数的Jinja2模板来定制文件输出。

Template: file.html

{% from macros import embed %}

<!DOCTYPE html>
<html lang="en">
  {% block head %}
  <head>
    {% block inner_head %}
      <meta charset="utf-8">
      <title>{% block title %}{{ title | e if title else "Bokeh Plot" }}{% endblock %}</title>
      {% block preamble %}{% endblock %}
      {% block resources %}
        {% block css_resources %}
          {{ bokeh_css | indent(8) if bokeh_css }}
        {% endblock %}
        {% block js_resources %}
          {{ bokeh_js | indent(8) if bokeh_js }}
        {% endblock %}
      {% endblock %}
      {% block postamble %}{% endblock %}
    {% endblock %}
  </head>
  {% endblock %}
  {% block body %}
  <body>
    {% block inner_body %}
      {% block contents %}
        {% for doc in docs %}
          {{ embed(doc) if doc.elementid }}
          {% for root in doc.roots %}
            {% block root scoped %}
              {{ embed(root) | indent(10) }}
            {% endblock %}
          {% endfor %}
        {% endfor %}
      {% endblock %}
      {{ plot_script | indent(8) }}
    {% endblock %}
  </body>
  {% endblock %}
</html>

bokeh_model¶

彻底记录Bokeh模型类。

这个 bokeh-model 指令将自动记录Bokeh模型子类的所有属性（包括Bokeh属性）。还将生成一个显示所有可能的JSON字段的JSON原型。

此指令将Bokeh模型类的名称作为参数，将其模块作为选项：

.. bokeh-model:: Foo
    :module: bokeh.sphinxext.sample

实际案例

对于以下定义 bokeh.sphinxext.sample.Foo ：

class Foo(Model):
    """ This is a Foo model. """
    index = Either(Auto, Enum('abc', 'def', 'xzy'), help="doc for index")
    value = Tuple(Float, Float, help="doc for value")

上述用法产生输出：

class Foo(*args, **kwargs)[源代码]¶
基类：bokeh.model.Model

这是一个Foo模型。

index¶

属性类型： Either （ Auto ， Enum （枚举（abc、def、xzy）））

索引文档
js_event_callbacks¶
属性类型： Dict （ String ， List （ Instance （ CustomJS ) ) )

事件名称到列表的映射 CustomJS 回调。

通常，应该使用 Model.js_on_event 方法：
callback = CustomJS(code="console.log('tap event occurred')")
plot.js_on_event('tap', callback)
js_property_callbacks¶
属性类型： Dict （ String ， List （ Instance （ CustomJS ) ) )

属性名到列表的映射 CustomJS 回调，在创建文档时在BokehJS侧设置。

通常，应该使用 Model.js_on_change 方法：
callback = CustomJS(code="console.log('stuff')")
plot.x_range.js_on_change('start', callback)
name¶
属性类型： String

用户为此模型提供的任意名称。

当查询文档以检索特定的Bokeh模型时，这个名称非常有用。
>>> plot.circle([1,2,3], [4,5,6], name="temp")
>>> plot.select(name="temp")
[GlyphRenderer(id='399d53f5-73e9-44d9-9527-544b761c7705', ...)]
注解

对于提供的任何名称，不提供唯一性保证或其他条件，Bokeh也不以任何理由直接使用该名称。
subscribed_events¶

属性类型： List （ String ）

Python回调订阅的事件列表。对于这个模型，这是一组将从BokehJS传递回Python的事件。
tags¶
属性类型： List （ Any ）

附加到此模型的任意用户提供的值的可选列表。

当查询文档以检索特定的Bokeh模型时，此数据非常有用：
>>> r = plot.circle([1,2,3], [4,5,6])
>>> r.tags = ["foo", 10]
>>> plot.select(tags=['foo', 10])
[GlyphRenderer(id='1de4c3df-a83d-480a-899b-fb263d3d5dd9', ...)]
或者简单地将任何必要的元数据附加到可以通过 CustomJS 回调等。

注解

对于所提供的任何标签，不存在唯一性保证或其他条件，Bokeh也不以任何理由直接使用这些标签。
value¶

属性类型： Tuple （ Float ， Float ）

价值凭证

apply_theme(property_values)¶

应用一组主题值，这些值将被使用而不是默认值，但不会覆盖应用程序集值。

传入的字典可以保持原样，并与其他实例共享以节省内存（因此无论是调用方还是 HasProps 实例应该修改它）。

参数

property_values (dict) -- 主题值用于替代默认值

返回

没有

classmethod dataspecs()¶

收集所有人的名字 DataSpec 类的属性。

这种方法总是遍历类层次结构并包含在任何父类上定义的属性。

返回

名称 DataSpec 性质

返回类型

set[str]

classmethod dataspecs_with_props()¶

收集一张记录所有人姓名的字典 DataSpec 类的属性。

这种方法总是遍历类层次结构并包含在任何父类上定义的属性。

返回

名称和 DataSpec 性质

返回类型

dict[str, DataSpec]

equals(other)¶

模型的结构相等。

参数

other (HasProps) -- 要比较的另一个实例

返回

如果属性在结构上相等，则为True，否则为False
js_link(attr, other, other_attr, attr_selector=None)¶
使用JavaScript链接两个Bokeh模型属性。

这是一种方便的方法，它简化了添加一个CustomJS回调，以便在另一个Bokeh模型属性更改值时更新它。

参数

attr (str) -- 此模型上的Bokeh属性的名称

other (Model) -- 要链接到的Bokeh模型自我属性

other_attr (str) -- 上的财产 other 连接在一起

attr_selector (Union[int, str]) -- 链接可订阅项中的项的索引 attr

在版本1.1中添加

引发

ValueError --

实际案例

此代码与 js_link ：
select.js_link('value', plot, 'sizing_mode')
相当于：
from bokeh.models import CustomJS
select.js_on_change('value',
    CustomJS(args=dict(other=plot),
             code="other.sizing_mode = this.value"
    )
)
此外，要使用属性选择器将范围滑块的左侧附加到绘图的x_范围：
range_slider.js_link('value', plot.x_range, 'start', attr_selector=0)
相当于：
from bokeh.models import CustomJS
range_slider.js_on_change('value',
    CustomJS(args=dict(other=plot.x_range),
             code="other.start = this.value[0]"
    )
)
js_on_change(event, *callbacks)¶
附A CustomJS 对任意BokehJS模型事件的回调。

在BokehJS方面，模型属性的更改事件具有以下形式 "change:property_name" . 为了方便起见，如果传递给此方法的事件名也是模型上某个属性的名称，那么它的前缀将是 "change:" 自动：
# these two are equivalent
source.js_on_change('data', callback)
source.js_on_change('change:data', callback)
但是，除了属性更改事件之外，还有其他类型的事件可以用来响应。例如，每当数据流式传输到 ColumnDataSource 使用 "stream" 源上的事件：
source.js_on_change('streaming', callback)
layout(side, plot)¶

classmethod lookup(name)¶

找到 PropertyDescriptor 对于类上的Bokeh属性，给定属性名。

参数

name (str) -- 要搜索的属性的名称

返回

名为的属性的描述符 name

返回类型

PropertyDescriptor
on_change(attr, *callbacks)¶
在此对象上添加回调以在 attr 变化。

参数

attr (str) -- 此对象的属性名

*callbacks (callable) -- 要注册的回调函数

返回

没有

例子：
widget.on_change('value', callback1, callback2, ..., callback_n)
classmethod properties(with_bases=True)¶

收集此类的属性名称。

这种方法 任选地 遍历类层次结构并包含在任何父类上定义的属性。

参数

with_bases (bool, optional) -- 是否在结果中包含在父类上定义的属性。（默认值：True）

返回

属性名称

返回类型

set[str]

classmethod properties_containers()¶

收集此类上所有容器属性的名称。

这种方法总是遍历类层次结构并包含在任何父类上定义的属性。

返回

容器属性名称

返回类型

set[str]

classmethod properties_with_refs()¶

收集该类上也有引用的所有属性的名称。

这种方法总是遍历类层次结构并包含在任何父类上定义的属性。

返回

具有引用的属性的名称

返回类型

set[str]

properties_with_values(include_defaults: bool = True) → Dict[str, Any]¶

收集将属性名称映射到其值的dict。

这种方法总是遍历类层次结构并包含在任何父类上定义的属性。

跳过不可序列化的属性，属性值采用“序列化”格式，这可能与通常从属性中读取的值略有不同；此方法的目的是返回无损重建对象实例所需的信息。

参数

include_defaults (bool, optional) -- 是否包含自创建对象后尚未显式设置的属性。（默认值：True）

返回

从属性名到属性值的映射

返回类型

dict

query_properties_with_values(query, include_defaults=True)¶

查询的属性值 HasProps 带有谓词的实例。

参数

query (callable) -- 接受属性描述符并返回True或False的可调用文件

include_defaults (bool, optional) -- 是否包含尚未由用户显式设置的属性（默认值：True）

返回

为匹配的属性映射属性名称和值

返回类型

dict

references()¶

返回全部 Models 此对象引用的。

remove_on_change(attr, *callbacks)¶

从此对象中删除回调

select(selector)¶

查询此对象及其所有引用以查找与给定选择器匹配的对象。

参数

selector (JSON-like) --

返回

SEQ [模型]

select_one(selector)¶

查询此对象及其所有引用以查找与给定选择器匹配的对象。如果找到多个对象，则引发错误。返回单个匹配的对象，如果找不到任何对象，则返回无：param selector:：type selector:JSON like

返回

模型

set_from_json(name, json, models=None, setter=None)¶

从JSON设置此对象的属性值。

参数

name -- （str）：要设置的属性的名称

json -- （JSON value）：要设置为的属性的值

models (dict or None, optional) -- 模型ID到模型的映射（默认值：无）在要更新的属性也有引用的值的情况下，需要这样做。

setter (ClientSession or ServerSession or None, optional) -- 这是用来防止“飞镖”更新到博克应用程序。在Bokeh服务器应用程序的上下文中，对属性的传入更新将使用正在进行更新的会话进行注释。此值通过更新触发的任何后续更改通知传播。会话可以将事件设置程序与其自身进行比较，并禁止任何源自自身的更新。

返回

没有

set_select(selector, updates)¶

更新与具有指定属性/值的给定选择器匹配的对象将更新。

参数

selector (JSON-like) --

updates (dict) --

返回

没有

themed_values()¶

获取任何主题提供的覆盖。

结果以dict形式从属性名返回到值，或者 None 如果没有主题覆盖此实例的任何值。

返回

不记名

to_json(include_defaults)¶

返回此对象属性的字典，只包含“JSON类型”（string、number、boolean、none、dict、list）。

对其他对象的引用被序列化为“refs”（只是对象ID和类型信息），因此反序列化程序需要单独拥有这些其他对象的完整属性。

没有对应的 from_json() 因为反序列化对象通常是在文档上下文中完成的（因为文档可以解析引用）。

在大多数情况下，最好序列化和反序列化整个文档。

参数

include_defaults (bool) -- 是否包含未从默认值更改的属性

to_json_string(include_defaults)¶

返回编码此对象属性的JSON字符串。

对其他对象的引用被序列化为引用（仅对象ID和类型信息），因此反序列化程序将需要单独拥有这些其他对象的完整属性。

没有对应的 from_json_string() 因为反序列化对象通常是在文档上下文中完成的（因为文档可以解析引用）。

在大多数情况下，最好序列化和反序列化整个文档。

参数

include_defaults (bool) -- 是否包含未从默认值更改的属性

trigger(attr, old, new, hint=None, setter=None)¶

unapply_theme()¶

删除所有主题值并恢复默认值。

返回

没有
update(**kwargs)¶
从给定的关键字参数更新对象的属性。

返回

没有

实际案例

以下是等效的：
from bokeh.models import Range1d

r = Range1d

# set properties individually:
r.start = 10
r.end = 20

# update properties together:
r.update(start=10, end=20)
update_from_json(json_attributes, models=None, setter=None)¶

对象的属性从字典中更新。

参数

json_attributes -- （JSON dict）：要更新的属性和值

models (dict or None, optional) -- 模型ID到模型的映射（默认值：无）在要更新的属性也有引用的值的情况下，需要这样做。

setter (ClientSession or ServerSession or None, optional) -- 这是用来防止“飞镖”更新到博克应用程序。在Bokeh服务器应用程序的上下文中，对属性的传入更新将使用正在进行更新的会话进行注释。此值通过更新触发的任何后续更改通知传播。会话可以将事件设置程序与其自身进行比较，并禁止任何源自自身的更新。

返回

没有

property document¶

这个 Document 此模型附加到（可以是 None ）
property struct¶
此模型的Bokeh协议“结构”，即以下形式的dict：
{
    'type' : << view model name >>
    'id'   : << unique model id >>
}
此外，可能还有 subtype 字段（如果此模型是子类型）。
JSON Prototype
{
  "id": "16032",
  "index": "auto",
  "js_event_callbacks": {},
  "js_property_callbacks": {},
  "name": null,
  "subscribed_events": [],
  "tags": [],
  "value": null
}

这个 bokeh-model 方向可以显式使用，但也可以与 bokeh_autodoc 延伸。

bokeh_options¶

彻底记录Bokeh选项类。

这个 bokeh-options 指令将自动将Bokeh Options类的所有属性记录在“Keyword Args”标题下。

此指令将Bokeh Options子类的名称作为参数，将其模块作为选项：

.. bokeh-options:: Opts
    :module: bokeh.sphinxext.sample

实际案例

对于以下定义 bokeh.sphinxext.sample.Opts ：

class Opts(Options):
    """ This is an Options class """

    host = String(default="localhost", help="a host to connect to")
    port = Int(default=5890, help="a port to connect to")

上述用法产生输出：

关键字参数：

主办 (String )：要连接到的主机（默认值：“localhost”）

港口 (Int )：要连接的端口（默认值：5890）

bokeh_palette¶

生成单个调色板的内联视觉表示。

这个 :bokeh-palette: 角色可通过提供以下任一项与一起使用：

调色板名称来自 bokeh.palettes ，例如 Spectral9
调色板函数 bokeh.palettes 用参数调用，例如。 viridis(12)
明确的颜色列表： ['#000000', '#333333', '#666666', '#999999', '#cccccc', '#ffffff']

指令的以下用法：

* by name: :bokeh-palette:`Spectral9`

* by function: :bokeh-palette:`viridis(12)`

* by list: :bokeh-palette:`['#000000', '#333333', '#666666', '#999999', '#cccccc', '#ffffff']`

生成输出：

按姓名：

按功能：

按列表：

调色板样例高度为20像素。对于短于20种颜色的调色板，样例的默认宽度为20像素。如果给定更大的调色板，则HTML跨距的宽度将逐渐减小，最小值为一个像素。例如，使用表达式显示完整的Viridis调色板

:bokeh-palette:`viridis(256)`

将生成输出：

bokeh_palette_group¶

在Bokeh调色板组中生成调色板的视觉表示。

这个 bokeh.palettes 模块公开诸如 mpl ， brewer 和 d3 提供选项板组。这个 bokeh-palette-group 指令接受其中一个组的名称，并为组中的每个调色板生成一个可视化的颜色矩阵。

例如，指令的以下用法：

.. bokeh-palette-group:: mpl

生成输出：

Cividis

3

4

5

6

7

8

9

10

11

Inferno

3

4

5

6

7

8

9

10

11

Magma

3

4

5

6

7

8

9

10

11

Plasma

3

4

5

6

7

8

9

10

11

Viridis

3

4

5

6

7

8

9

10

11

注解

这个扩展假定Bootstrap和JQuery都存在（Bokeh文档主题就是这样）。如果在Bokeh文档之外使用这个主题，一定要手动包含这些资源。

bokeh_plot¶

在sphinxhtml文档中包含Bokeh图。

对于其他输出类型，占位符文本 [graph] 将生成。

这个 bokeh-plot 指令可通过以下任一方式使用：

源文件的路径 作为指令的参数：

.. bokeh-plot:: path/to/plot.py

注解

.py脚本不会自动扫描！为了在.py扫描过程中包含某些目录，请使用sphinx中的以下指令配置文件文件：bokeh_plot_pyfile_include_dirs= [“dir1”，“dir2”]

内联代码 作为指令的内容：

.. bokeh-plot::

    from bokeh.plotting import figure, output_file, show

    output_file("example.html")

    x = [1, 2, 3, 4, 5]
    y = [6, 7, 6, 4, 5]

    p = figure(title="example", plot_width=300, plot_height=300)
    p.line(x, y, line_width=2)
    p.circle(x, y, size=10, fill_color="white")

    show(p)

当在docstrings中使用时，此指令也可以与Sphinx autodoc一起使用。

这个 bokeh-plot 指令接受以下选项：

源位置（enum（'above'，'below'，'none'）：: 定位格式化源代码块的位置（如果有）。
线路编号（布尔）：: 是否随源显示行号。

实际案例

上面的内联示例代码生成以下输出：

from bokeh.plotting import figure, output_file, show

output_file("example.html")

x = [1, 2, 3, 4, 5]
y = [6, 7, 6, 4, 5]

p = figure(title="example", plot_width=300, plot_height=300)
p.line(x, y, line_width=2)
p.circle(x, y, size=10, fill_color="white")

show(p)

bokeh_prop¶

彻底记录Bokeh属性属性。

这个 bokeh-prop 指令为Bokeh模型属性生成文档，包括指向相关属性类型的交叉链接。此外，还会显示每个属性的帮助字符串。

此指令的名称为 (类.attr) 将Bokeh属性作为参数，将模块作为选项：

.. bokeh-prop:: Bar.thing
    :module: bokeh.sphinxext.sample

实际案例

对于以下定义 bokeh.sphinxext.sample.Bar ：

class Bar(Model):
    """ This is a Bar model. """
    thing = List(Int, help="doc for thing")

上述用法产生输出：

thing¶

属性类型： List （ Int ）

医生的事

这个 bokeh-prop 方向可以显式使用，但也可以与 bokeh_autodoc 延伸。

bokeh_releases¶

将所有Bokeh发行说明发布到一个页面上。

此指令收集 docs/releases 子目录，并将它们包含在 反转版本顺序 . 典型用法：

:tocdepth: 1

.. toctree::

.. bokeh-releases::

为了避免有关孤立文件的警告，请在Sphinx中添加以下内容 conf.py 文件：

exclude_patterns = ['docs/releases/*']

bokeh_sitemap¶

生成一个 sitemap.txt 帮助搜索索引。

sitemap.txt 是文档网站中所有页面的纯文本列表。每个URL都列在文本文件的一行中。它是机器可读的，搜索引擎使用它来知道哪些页面可以用于索引。

生成站点地图所需的全部操作就是列出此模块 bokeh.sphinxext.sitemap 在Sphinx配置文件的扩展名列表中 conf.py .

collapsible_code_block¶

输出到HTML时，在可折叠部分显示代码块。

此指令使用可折叠代码块的标题：

.. collapsible-code-block:: python
    :heading: Some Code

            print("Hello, Bokeh!")

本指令与本标准相同 code-block 斯芬克斯提供的指令，增加了一个新选项：

标题（字符串）：: 可折叠块的标题。单击标题可展开或折叠块。

实际案例

上面的内联示例代码生成以下输出：

Some Code

    print("Hello, Bokeh!")