HTMLトピック開発¶

バージョン 0.6 で追加.

注釈

このドキュメントでは、あなた自身のトピックを作成するための情報を提供します。予め存在するHTMLトピックのみをご利用になりたい場合は、ご参照ください HTMLトピックそれがそうです。

Sphinxは、以下のようにHTML出力の外観を変更することをサポートしています。 テーマ それがそうです。トピックはHTMLテンプレート，スタイルテーブル，その他の静的ファイルの集合である.また、継承するトピック、使用する強調表示スタイル、およびトピックの外観をカスタマイズするオプションを指定するプロファイルがあります。

テーマはプロジェクトとは無関係でなければならないので、それらは変更することなく、異なるプロジェクトに使用することができる。

注釈

見 Sphinxの開発拡張開発テーマに役立つかもしれないもっと多くの情報を得る。

テーマを作る¶

トピックはディレクトリまたはzipfile(その名前はトピック名)の形式を採用し，以下を含む：

A theme.conf ファイルです。
HTMLテンプレート(必要であれば).
A static/ 生成時に静的ディレクトリを出力する任意の静的ファイルにコピーするディレクトリを含む.これらは、画像、スタイル、スクリプトファイルであってもよい。

♪the theme.conf ファイルはINI形式です 1 (標準Python可読 ConfigParser モジュール)は，以下の構成を持つ.

[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename
sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html

[options]
variable = default value

♪the 継承 “基本テーマ”を提供する名称、または none それがそうです。基本的なトピックは、欠落したテンプレートを特定するために使用される(使用する場合、ほとんどのトピックは、ほとんどのテンプレートを提供する必要 basic 基本テーマ)として、そのオプションが継承され、そのすべての静的ファイルも使用される。様式表を継承したい場合は、CSS‘で含めてください @import あなた自身の世界で。
♪the スタイル表. HTMLタイトルで参照されるCSSファイルを提供する名前を設定します。複数のCSSファイルが必要でしたら、CSSのを通ってください @import カスタムHTMLテンプレートを使用して追加する <link rel="stylesheet"> 必要に応じてラベルを添付する。設ける html_style 構成値は、この設定を上書きします。
♪the pygments_style ハイライト表示のためのPygmentsスタイルを提供する名前を設定します。このオプションはユーザが pygments_style 値を配置する。
♪the pygments_dark_style CSSメディアクエリ時に強調表示のためのPygmentsスタイルを提供する名前を設定する (prefers-color-scheme: dark) 計算結果はTrueである.ページに注入されて使用されます add_css_file() それがそうです。
♪the サイドバー. サイドバーのコンマ区切りを構築するためのサイドバーテンプレートリストを設定します。このオプションはユーザが html_sidebars 値を配置する。
♪the オプション 部分は変数名とデフォルト値対を含む.ユーザーはこれらのオプションを中でカバーすることができます html_theme_options 全てのテンプレートからアクセスすることができます theme_<name> それがそうです。

バージョン 1.7 で追加: サイドバー設置

あなたのテーマをPythonパッケージとして配布します¶

テーマを配布する一つの方法として、Pythonパッケージを使用することができます。Pythonパッケージはユーザーに簡単な設定方法を持ってきました。

テーマをPythonパッケージとして配布するには、名前の入口ポイントを定義してください sphinx.html_themes あなたの setup.py 文書を作成し setup() 関数はあなたのテーマを登録するために、方法は使用します add_html_theme() インターフェースはその中にあります：

# 'setup.py'
setup(
    ...
    entry_points = {
        'sphinx.html_themes': [
            'name_of_theme = your_package',
        ]
    },
    ...
)

# 'your_package.py'
from os import path

def setup(app):
    app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))

テーマパッケージに2つ以上のトピックが含まれている場合は、呼び出してください add_html_theme() 二回か二回以上です。

バージョン 1.2 で追加: ‘Shinx_Themes’Entry_Points機能。

バージョン 1.6 で非推奨: sphinx_themes Entry_Pointsは破棄されました。

バージョン 1.6 で追加: sphinx.html_themes 入口点機能。

テンプレート化する¶

♪the guide to templating もしあなたが自分のテンプレートを作成したいなら、これは非常に有用だ。覚えておくべき重要な点は、Sphinxがテンプレートを検索する手順です。

まずユーザの templates_path カタログです。
そして、選定されたテーマの中で。
そして、その基本的なテーマの中で、その基礎的なテーマなど。

基本トピックのテンプレートを同じ名前で拡張する場合は、明示的なディレクトリとしてトピック名を使用してください： {{% extends "basic/layout.html" %}} それがそうです。ユーザーから templates_path テンプレートは、テンプレート文書に記述されている“感嘆符”文法を使用することができます。

静的テンプレート.¶

トピック·オプションは、ユーザがカスタム·スタイル·テーブルを作成することなく、トピックをより容易に構成できることを意味するため、静的ファイルおよびHTMLファイルにテンプレートを提供することができる必要がある。したがって，Sphinxはいわゆる“静的テンプレート”をサポートし，以下のようになる.

もし static/ トピックのディレクトリ(またはユーザの静的パスで) _t これは，テンプレートエンジンによって処理される.♪the _t 最終ファイル名から保留されます。例えば経典主題には書類がある static/classic.css_t これは、テンプレートを使用してカラーオプションをスタイルテーブルに入れます。古典的なトピックを用いて文書を生成する場合，出力リストには含まれる _static/classic.css すべてのテンプレートタグがその中で処理されているファイル.

HTMLテンプレートにはカスタムページメタデータを用いる.¶

任意のキー/値対 field lists そこに置かれているのは その前に ページを構築する際には，ページタイトルをJJJAテンプレートに利用することができる. meta 属性です。例えば、ページの最初のタイトルの前に以下のテキストがある場合：

:mykey: My value

My first title
--------------

そして，JJJAテンプレートでこれにアクセスすることができ，以下のようになる.

{%- if meta is mapping %}
    {{ meta.get("mykey") }}
{%- endif %}

この小切手に注意してください meta 辞書(JJJA用語の“マッピング”)であり、このように使用することが有効であることを保証する。

カスタムテンプレート関数を定義する.¶

場合によっては、Pythonで自分の関数を定義するのに有用で、その後テンプレートでこれらの関数を使用したいと思います。例えば、テンプレート値を挿入することを望む場合、そのロジックは、アイテム内のユーザの構成に依存するか、または重要なチェックを含み、テンプレート内の不正確な構成に友好的なエラーメッセージを提供することを望む場合。

あなた自身のテンプレート関数を定義するためには、モジュールで2つの関数を定義する必要があります。

A ページコンテキストイベントハンドラ (または) 登記 )関数。これは Sphinx アプリケーションはイベントによってコールバックされる.
A テンプレート関数 あなたはあなたの精霊テンプレートで使用されるだろう。

まず，登録関数を定義し，その関数を受け取る. html-page-context それがそうです。

登録関数では，JJJAで使用したいテンプレート関数を定義する.テンプレート関数は、テンプレート中にJJJAが使用する文字列を含む文字列またはPythonオブジェクト(リスト、辞書)を返す必要があります。

注釈

テンプレート関数は，登録関数に渡されるすべての変数にアクセスすることができる.

登録関数の末尾には，以下の命令を用いてSphinxアプリケーションのコンテキストにテンプレート関数を追加する. context['template_func'] = template_func それがそうです。

最後に内線の setup() 関数は，登録関数を追加する. html-page-context それがそうです。

# The registration function
 def setup_my_func(app, pagename, templatename, context, doctree):
     # The template function
     def my_func(mystring):
         return "Your string is %s" % mystring
     # Add it to the page's context
     context['my_func'] = my_func

 # Your extension's setup function
 def setup(app):
     app.connect("html-page-context", setup_my_func)

現在、JJJAのこの機能にアクセスすることができます。以下のようになります。

<div>
{{ my_func("some string") }}
</div>

構築資産に自分の静的ファイルを追加します¶

拡張子を使用して自分の構築リソース(例えば、CSSまたはJavaScriptファイル)をパッケージ化している場合、それらを置くことを確認する必要があります。 _static/ HTMLが出力するフォルダ。そのために生成されたものに直接コピーすることができます _static/ フォルダは，通常イベントを介してリンクされる.以下は、この動作を完了するいくつかの例示的なコードである。

def copy_custom_files(app, exc):
    if app.builder.format == 'html' and not exc:
        staticdir = path.join(app.builder.outdir, '_static')
        copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir)

def setup(app):
    app.connect('builder-inited', copy_custom_files)

ユーザ構成に応じてJavaScriptを注入する¶

あなたの拡張にJavaScriptを使用すれば、ユーザが彼らのSphinx構成を使用してその動作を制御することを可能にするのは有用です。しかし、もしあなたのJavaScriptが静的ライブラリの形で現れた場合(JJJAを使用して構築されません)、これは難しいかもしれません。

ユーザ配置により，JavaScript空間に変数を注入することができる2つの方式がある.

まず、追加することができます _t 拡張子に含まれる任意の静的ファイルの末尾に追加します。これにより、Sphinxがテンプレートエンジンを使用してこれらのファイルを処理し、変数および制御アクションを埋め込むことができます。

たとえば，以下のJavaScript構造：

mymodule/
├── _static
│   └── myjsfile.js_t
└── mymodule.py

HTMLの構築出力には、以下の静的ファイルが配置されます。

_build/
└── html
    └── _static
        └── myjsfile.js

見静的テンプレート. より多くの情報を得ることができます

第二に、ご利用いただけます Sphinx.add_js_file() メソッドは，ファイルを指すのではない.通常、この方法は、新しいJavaScriptファイルをサイトに挿入するために使用される。しかしもしあなたがそうしたら not “body”パラメータに文字列を渡すのではなく、ファイルパスを渡し、その後、テキストをJavaScriptとしてあなたのサイトヘッダに挿入します。これにより、PythonからプロジェクトのJavaScriptに変数を挿入することができます。

たとえば，次のコードはユーザが配置した値を読み込み，その値をJavaScript変数として挿入し，拡張されたJavaScriptコードはこの変数を使用する可能性がある：

# This function reads in a variable and inserts it into JavaScript
def add_js_variable(app):
    # This is a configuration that you've specified for users in `conf.py`
    js_variable = app.config['my_javascript_variable']
    js_text = "var my_variable = '%s';" % js_variable
    app.add_js_file(None, body=js_text)
# We connect this function to the step after the builder is initialized
def setup(app):
    # Tell Sphinx about this configuration variable
    app.add_config_value('my_javascript_variable')
    # Run the function after the builder is initialized
    app.connect('builder-inited', add_js_variable)

したがって、この変数の存在に依存するコードをトピックで使用することができます。ユーザはその中に変数の値を定義することで，その変数の値を制御することができる. conf.py ファイルです。

1: これは実行可能なPythonファイルではなく、 conf.py なぜなら、テーマが共有されれば、不必要な安全リスクをもたらすからだ。

Table of Contents

前のトピックへ

次のトピックへ