書類¶

Bokehへの投稿は，十分かつ適切な文書支援を含む場合にのみ受け入れられる.本節では，文書をローカルに構築.編集する方法について概説し，項目が従う約束について述べる.

文書作成を支援することはプロジェクトに貢献する最も価値のある方法の一つだ。これはまた良い入門方式であり、自分を新たな貢献者として紹介する。打鍵ミスや他の小さな文書誤りを解決する可能性が最も高い方法は，その問題に気づいた者がただちに引き込み要求を提出して訂正を行うことである. これはいつも感謝します！ 急速な修復のほかにも一連の Open Docs Issues GitHubでは、誰でも助けが必要な任務を見ることができる。

文書を処理する¶

Sphinx HTML文書を生成するために用いられる.Bokehは生まれつきJavaScriptに依存しているため，公式の構築構成は他の出力フォーマットをサポートしていない.本節では，Sphinxを用いてソースコードからBokeh文書を構築する方法について述べる.

インストール要求¶

ソースコードから文書を構築するために、まず中の説明に従って操作することをお勧めします設置を開始するそれがそうです。

Bokeh GitHubリポジトリまたは発行パケットのサイズ制限のため、文書内のいくつかのBokeh例は、Bokeh GitHubリポジトリまたは発行パッケージに含まれない例示的なデータに依存する。

Bokehのインストール後、BashまたはWindowsプロンプトで以下のコマンドを実行することでサンプルデータを取得することができます。

bokeh sampledata

見サンプルデータサンプルデータのダウンロード方法の代替説明については、参照されたい。

文書を構築する¶

完全な文書を生成するには、まずナビゲーションしてください sphinx Bokehソース木のサブディレクトリ。

cd sphinx

Sphinx使用 make 構築プロセスを制御するためのツール.Bokeh Makefileの最も一般的な目標は：

clean: 以前に構築した文書出力をすべて削除する.すべての出力は次の構築時に最初から生成される.
html: (例えば、前回の生成以来、入力ソースファイルが変更されたので、任意の未生成または再生成を必要とするHTML出力が生成される)。
serve: サーバを起動して文書を提供し，Webブラウザを開いて表示する.JavaScriptファイルに関連しているため，文書の多くの部分を完全に見るためには，実際のサーバを起動しなければならないことに注意されたい.

例えば、docs buildディレクトリをクリーニングするためには、コマンドラインで以下のコマンドを実行してください。

make clean

複数の目標を単一の目標に統合することができる make 召喚する。たとえば，文書をクリーニングし，先頭からすべてのHTML文書を生成し，ブラウザを開いて結果を表示するコマンドを実行する.

make clean html serve

デフォルトでは，構築した文書がCDNから最新のBoehJSをロードする.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

ソースコード文書¶

文書文字列およびモデル支援はPythonインタプリタから取得できるが、完全なものを自動生成するためにSphinx構築によって処理される参考にするそれがそうです。

Bokehはいくつかの汎用的な約束を使用して一致した文書パターンを作成する。

文書文字列¶

私たちは Sphinx Napoleon 我々の参照文書のために文書文字列を処理する.

全ての文書文字列は Google Style Docstrings それがそうです。Docstringは通常動詞で始まり，短い文で関数やメソッドの役割を説明すべきである.例えば，“動詞優先”パターン：

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

"""

次のより冗長な文：

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

"""

関数および方法のDocstringは、一般に、以下の部分を含むべきである。

Args (関数がパラメータを持たない限り)
Returns (関数が戻ったばかりでも None ）

パラメータの短い記述は，暗黙的な“is”を挿入して完全な文を構成するように書かれるべきである.例：

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

“TITLE_FONTはストーリータイトルのためのフォントである”と合理的に理解できる。

完全な例は以下のようになる可能性がある。

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.
    """)

叙事的文献¶

記述的文書は，文書文字列やBokeh属性支援文字列から自動生成されないすべての文書からなる.これには“ユーザガイド”，“クイック入門”などが含まれる.これらの文書のソースコードは，標準的なSphinx再構成テキスト(REST)ファイルであり，これらのファイルは 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バージョンは、このコンテンツをすべてのバージョンのリストに自動的に追加します。