Sphinxのインストールから、外部テーマ(Bootswatch)利用までの解説

スポンサードリンク

本稿ではPythonモジュール”Sphinx”に関する

  • インストール方法
  • プロジェクト作成方法
  • 標準テーマ変更方法
  • 外部テーマ(Bootswatch)変更方法

について解説します。

Sphinxに関する詳しい解説などは以下サイトを御覧ください。
Sphinx日本ユーザー協会

使用環境

  • Mac OSX El Capitan
  • Python3.5.1
  • VirtualEnv

今回は仮想環境を作成しインストールしていますが、
この手順は各自の仮想環境モジュールをご使用いただくか、こだわりがなければ不要です。

インストール方法

任意の場所に仮想環境を作成し、起動します。

続いて、Sphinxモジュールをpipを用いてインストールします。

ここまでで、Sphinxのインストールは完了です。

プロジェクト作成

任意の場所にプロジェクト専用のフォルダを作成し、
その中でsphinx-quickstartコマンドを実行します。

コマンド実行すると、あらゆるオプションに関して質問されますが、基本Enterキーを押しておけば問題ありませんが、

  • ProjectName
  • Author Name
  • Version

の3つのみ入力必須項目となっていますので、適切に入力してください。
1項目言語設定がありますが、日本語にする場合はjaと入力し続行してください。

プロジェクト作成完了後

を実行すると、カレントディレクトリの_build/html内にHTMLが生成されます。
_build/html/index.htmlをブラウザで表示すると、ドキュメントが生成されていることがわかります。

標準テーマの変更

テーマ変更に関する設定は、プロジェクトフォルダ(今回はMyProject)内にある
conf.pyで行います。

conf.py

の文字列部分を変更することで標準テーマを変更することができます。

変更後は忘れずに

を行いましょう。

標準テーマは以下の9つがあります。

  • default
  • basic
  • sphinxdoc
  • scrolls
  • agogo
  • nature
  • pyramid
  • haiku
  • traditional
  • epub

使用できる標準テーマイメージは以下サイトに掲載されています。
標準テーマ集

外部テーマの使用

Sphinxでは、外部テーマを使用することも可能です。
今回はBootswatchテーマを使用して解説します。
Bootswatch

・ Bootswatchのインストール
引き続き仮想環境内で作業します。

・ BootswatchテーマのSphinxへの設定
これについても、プロジェクトフォルダ内のconf.pyで設定します。

まずはじめに、conf.pyの先頭行でモジュールをインポートします。
コメントはつけないよう気をつけてください。

conf.py

引き続き、テーマの保存されているディレクトリ
及びテーマ名を設定します。

conf.py

Bootwatch公式ドキュメンテーションではhtml_theme_pathの設定に専用の関数が用意されているとの記載がありましたが、私の環境ではエラーが出たため、モジュールへの相対パスで記載しています


追記:yuntas様ご指摘
conf.py の以下コメントアウトを解除すれば解決するようです。

conf.py

次に、どのBootwatchテーマを使用するかを先程のコードの真下に指定します。
テーマの種類についてはこちらを参照ください。
Bootswatch

conf.py

こちらも変更後は忘れずに

を行いましょう。

以上で、外部テーマの設定が終了しました。

シェアする

  • このエントリーをはてなブックマークに追加

フォローする

スポンサードリンク