15

SphinxとReadTheDocsで使用されるテーマを独自のカスタム スタイルで拡張したいと考えています。

変更が反映されるようにするには、どうすればよいですか?

4

3 に答える 3

28

編集: 2021 年現在、次の回答は古くなっています。バージョン 1.8 以降のアプリケーション API を使用する代わりに使用html_css_files = []してくださいconf.py(執筆時点での現在の Sphinx バージョンは 4.1.1 です)。以下のadd_stylesheetオプションはadd_css_file、バージョン 1.8 で名前が変更されており、Sphinx 拡張機能の開発者向けのようです。

仮定

RTD doc セットには、次のような構造があります。

  • (ルートパス)
    • （この議論に関係のない他のもの）
    • _static/
    • _templates/
    • conf.py

また、デフォルトのテーマを使用して、sphinx-buildまたは使用してローカルでビルドしていますが、デプロイされたサーバーは代わりに を使用する場合があります。sphinx-autobuildsphinx-rtd-theme

ユースケース: ハットノート

この図では、「ハットノート」のカスタム スタイルを作成する方法を示します。この概念は、MediaWiki ドキュメントで一般的であり、RSTの構造にほぼ対応しています。admonitionここに示す内容を適用してカスタム CSS を作成し、それをドキュメント セットに含めることができます。

ステップ 1: カスタム CSS を作成する

_static/カスタム CSS ファイルは、ビルド プロセスとスクリプトが見つける場所であるため、ディレクトリの下のどこかに配置する必要があります。css/JavaScript ファイルなど、他のカスタマイズを追加する可能性があるため、サブディレクトリをお勧めします。

カスタム CSS ファイルを作成し、このディレクトリに配置します。ビルドで使用するテーマに既に存在する可能性があるものにオーバーレイとしてスタイル仕様を記述します。また、スタイルがテーマ内の既存のスタイルをオーバーライドするかどうかについても、何も想定しないでください。スタイルがデフォルトのものに関連していつ追加されるかを保証できないためです。

ハットノート用のカスタム CSS は次のとおりです。これを に保存しました_static/css/hatnotes.css。

.hatnote
{
    border-color: #c8c8c8 ;
    border-style: solid ;
    border-width: 1px ;
    font-size: x-small ;
    font-style: italic ;
    margin-left: auto ;
    margin-right: auto ;
    padding: 3px 2em ;
}
.hatnote-gray { background-color: #e8e8e8 ; color: #000000 ; }
.hatnote-yellow { background-color: #ffffe8 ; color: #000000 ; }
.hatnote-red { background-color: #ffe8e8 ; color: #000000 ; }
.hatnote-icon { height: 16px ; width: 16px ; }

ステップ 2: テンプレートにスタイルを追加する

デフォルトのテーマの場合、デフォルトをオーバーライドしlayout.htmlてカスタム CSS をレイアウトに追加するテンプレートを作成するだけで十分です。テンプレートの使用については、sphinxdoc.org で詳しく説明されています。オーバーライド テンプレートでは、css-files変数 (配列) にカスタム CSS ファイルの追加リストを設定するだけです。

これは、ハットノート CSS を追加する私のテンプレートです。として保存しました_templates/layout.html。

{% extends "!layout.html" %}
{% set css_files = css_files + [ "_static/css/hatnotes.css" ] %}

デフォルトのテーマで行う必要があるのはこれだけです。Sphinx/RTD テーマの場合は、追加の手順があります。</p>

ステップ 3: スタイルシートをテーマに追加する

Sphinx/RTD テーマの場合、テンプレートは無視されます。テンプレート メカニズムを使用する代わりにconf.py、CSS ファイルをアプリのテーマに追加する関数をファイルに追加する必要があります。conf ファイルがhtml_theme属性を設定する場所の近くに、次のようなものを追加します。

def setup(app):
  app.add_stylesheet( "css/hatnotes.css" )

今回_static/は、パスの前に何もないことに注意してください。add_stylesheet()関数はパスのその部分を想定しています。

ユースケースの仕上げ

デフォルト テーマと Sphinx/RTD テーマの両方にカスタム スタイルを設定したので、ドキュメントで実際に使用できます。

MediaWiki でストック ハットノートを「テンプレート」として定義するという通常のパラダイムに従って (申し訳ありませんが、Sphinx や RTD のテンプレートとは異なります)、includes/すべてのハットノートを保存するディレクトリを設定しました。

カスタム スタイル情報を使用してハットノートを作成する方法を次に示します。このファイルはincludes/hatnotes/stub-article.rst.

.. container:: hatnote hatnote-gray

   |stub| This article is a stub. Please improve the docs by expanding it.

.. |stub| image:: /images/icons/stub.png
          :class: hatnote-icon

ここでは、「スタブ」ハットノートをデフォルトのハットノート スタイル、灰色の背景を持つように設定し、「スタブ」アイコンをインライン イメージとして使用し、hatnote-iconそのイメージにスタイルを適用します。

これで、ファイルをドキュメントに含まれるリソースとして使用できます。

Foo Article
===========

.. include:: /includes/hatnotes/stub-article.rst

Blah blah I haven't written this article yet.

ローカルのデフォルト テーマを使用しているか、Sphinx/RTD テーマを使用しているかにかかわらず、_templates/layout.htmlテンプレートとconf.pyスクリプトをセットアップして追加したスタイルでハットノートがレンダリングされ、ディレクトリの下に配置したカスタム CSS ファイルが両方に含まれます_static/。

終了状態

ドキュメント リポジトリには次のものが含まれています。

  • (ルートパス)
    • _static/
      • css/
        • (カスタム CSS ファイル…)
    • _templates/
      • layout.html— (カスタム CSS をデフォルトのレイアウトに追加します)
    • conf.py— (アプリのテーマにカスタム CSS を追加する新機能付き)
于 2015-08-18T17:42:32.650 に答える