U
/e+ @ s d Z ddlmZ ddlmZ eeZddlZddl Z ddl
m Z ddl m
Z
mZmZ ddlmZ ddlmZ dd lmZmZ dd
lmZ dd lmZmZmZ dd l m Z dd
l m Z ddl m!Z! ddl"m#Z# ddl$m%Z% ddl&m'Z' ddl(m)Z) ddl*m+Z+ ddl,m-Z- dZ.e dZ/e- Z0G dd dej1ej2Z3G dd de)Z4d d Z5d d Z6d d! Z7d"d# Z8d$d$d%d&d'Z9d$d$d(d)d*Z:d+d, Z;dS )-a Include Bokeh plots in Sphinx HTML documentation.
For other output types, the placeholder text ``[graph]`` will
be generated.
The ``bokeh-plot`` directive can be used by either supplying:
**A path to a source file** as the argument to the directive::
.. bokeh-plot:: path/to/plot.py
.. note::
.py scripts are not scanned automatically! In order to include
certain directories into .py scanning process use following directive
in sphinx conf.py file: bokeh_plot_pyfile_include_dirs = ["dir1","dir2"]
**Inline code** as the content of the directive::
.. 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", width=300, height=300)
p.line(x, y, line_width=2)
p.circle(x, y, size=10, fill_color="white")
show(p)
This directive also works in conjunction with Sphinx autodoc, when
used in docstrings.
The ``bokeh-plot`` directive accepts the following options:
process-docstring (bool):
Whether to display the docstring in a formatted block
separate from the source.
source-position (enum('above', 'below', 'none')):
Where to locate the the block of formatted source
code (if anywhere).
linenos (bool):
Whether to display line numbers along with the source.
Examples
--------
The inline example code above produces the following output:
.. 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", width=300, height=300)
p.line(x, y, line_width=2)
p.circle(x, y, size=10, fill_color="white")
show(p)
) annotations)loggingN)getenv)basenamedirnamejoin)uuid4)nodes)choiceflag) SphinxError)copyfile ensuredirstatus_iterator)set_source_info)Document)autoload_static)Model)BokehDeprecationWarning )
PARALLEL_SAFE)BokehDirective)ExampleHandler)get_sphinx_resources)autoload_scriptBokehPlotDirectivesetupGOOGLE_API_KEYc @ s" e Zd Zedd ZejdfZdS )r c C sN |d }|d }|r(| j d| d | j | |rD| j d tjd S )N
script_tag height_hintzz
)bodyappendr ZSkipNode)Zvisitornoder r r# >/tmp/pip-unpacked-wheel-f5fndrjf/bokeh/sphinxext/bokeh_plot.py
visit_html s zautoload_script.visit_htmlN)__name__
__module__ __qualname__ staticmethodr% __func__htmlr# r# r# r$ r s
r c @ sT e Zd ZdZdZdd dd dd dZdd Zd
d d d
dZdd Zdd Z dS )r T c C s t | d kS Nr xr# r# r$ zBokehPlotDirective.c C s
t | dS )N)belowabovenone)r
r/ r# r# r$ r1 r2 c C s t | d kS r- r. r/ r# r# r$ r1 r2 )process-docstringsource-positionlinenosc
C s | \}}| jjdd}dt j d| d}z | |||\}}}}}W n6 tk
r } ztd| d| W 5 d } ~ X Y nX | jj
|t | jjf | dt | }
t
jdd|
gd g} | jd
d } |r| r| |d ng }
| ||\}}t||d
g}| |
| | | S )N/-zbokeh-content-z.jszError generating z:
. )idsr6 Fz)r r )process_args_or_contentenvdocnamereplacer hexprocess_source Exceptionr bokeh_plot_filesaddr r r targetoptionsgetparseprocess_code_blockr )selfsourcepathZdashed_docname js_filenamer js_path docstringr eZ target_idrG Zprocess_docstringZintror4 r3 Zautoloadr# r# r$ run s &zBokehPlotDirective.runstrz
str | NonerM rQ c C s | j dd}|dkr g g fS t|| }| j dd}tj||d|g d}t| | |dkrj|gg fS |dkr|g |gfS d S ) Nr7 r3 r5 r8 Fpython)languager8 classesr4 )rH rI _remove_module_docstringstripr Z
literal_blockr )rL rM rQ Zsource_positionr8 Z
code_blockr# r# r$ rK s
z%BokehPlotDirective.process_code_blockc
C s | j r| jrtd| jrFtd| jj | jj}d| j|fS | j d }td| jjd| | dst| jj
j |}z.t | }|
|fW 5 Q R W S Q R X W n: tk
r } z td| jjd|W 5 d }~X Y nX d S ) Nz7bokeh-plot:: directive can't have both args and contentz([bokeh-plot] handling inline content in
r z*[bokeh-plot] handling external content in z: r9 z&bokeh-plot:: error reading source for ) argumentscontentr logdebugr? r@ bokeh_plot_auxdirr
startswithappsrcdiropenreadrD )rL rN frR r# r# r$ r> s
$z*BokehPlotDirective.process_args_or_contentc C sn t t||| j\}}| }t| jj|}t|t|\}} t |d}
|
| W 5 Q R X | ||||fS )Nw) r Z_clear_extensions_evaluate_sourcer? Z_sphinx_height_hintr r` r RESOURCESrd write) rL rM rN rO rootrQ r rP Zjsr rf r# r# r$ rC s z!BokehPlotDirective.process_sourceN)
r& r' r( Z has_contentZoptional_argumentsZ option_specrS rK r> rC r# r# r# r$ r s r c C s8 t | jjd| j_t| jj t| jds4t | j_d S )NZ
bokeh_plotrE )r r? Z
doctreedirr` r hasattrsetrE rb r# r# r$ builder_inited s ro c C s t | jj}t|ddt|| jdd d}|D ]n\}}t| jj|t |}t
t | zt || W q. t
k
r } ztd|d| W 5 d }~X Y q.X q.d S )Nz copying bokeh-plot files... Zbrownc S s t | d S )Nr )r r/ r# r# r$ r1 r2 z build_finished..)Zstringify_funczcannot copy local file z
, reason: )sortedr? rE r len verbosityr ZbuilderZoutdirr r r r
OSErrorr )rb exceptionfilesZ
files_iterfileZdocpathrG rR r# r# r$ build_finished s rw c C s | j |j O _ d S r- )rE )rb r? Zdocnamesotherr# r# r$ env_merge_info
s ry c C sR | dt | jttjd | ddd | dt | dt | dt t
S ) z+ Required Sphinx extension setup function. z
bokeh-plot)r+ bokeh_missing_google_api_key_okTr+ zbuilder-initedzbuild-finishedzenv-merge-info) Z
add_directiver add_noder r+ Zadd_config_valueconnectro rw ry r rn r# r# r$ r
s r rT )rM returnc C s< d| kr | S t d kr0|jjr(| ddS td| dt S )Nr ZMISSING_API_KEYzThe GOOGLE_API_KEY environment variable is not set. Set GOOGLE_API_KEY to a valid API key, or set bokeh_missing_google_api_key_ok=True in conf.py to build anyway (with broken GMaps))r configrz rA r )rM r? r# r# r$ _replace_google_api_key s r rM filenamec C s t | |} t| |d}t }t ( d|jkr>tjdtd || W 5 Q R X |j rnt
d|j d| t |j
dkrt
dt |j
|j
d |jr|j nd fS )
Nr referenceignore)categoryzbokeh-plot:: error:
z
evaluating source:
r z;bokeh-plot:: directive expects a single Document root, got r )r r r warningscatch_warningsr@ filterwarningsr Zmodify_documenterror RuntimeErrorZ error_detailrq rootsdocrZ )rM r r? cdr# r# r$ rh - s
rh c C s( |d kr | S t dt | dd| S )Nz(\'\'\'|\"\"\")\s*z\s*(\'\'\'|\"\"\")r< )resubescaperU r# r# r$ rY C s rY )<__doc__
__future__r Z sphinx.utilr getLoggerr& r^ r r osr os.pathr r r uuidr Zdocutilsr Z docutils.parsers.rst.directivesr
r Z
sphinx.errorsr r
r r Zsphinx.util.nodesr Zbokeh.documentr Z bokeh.embedr Z bokeh.modelr Zbokeh.util.warningsr r< r Zbokeh_directiver Zexample_handlerr utilr __all__r ri ZGeneralElementr r ro rw ry r r rh rY r# r# r# r$ sB J
_