conf.py

conf.pyで設定できることを、自分が分かっている範囲でメモ。

よくわからないのは放置。


import sys,os

拡張のインポート。

sys.path.insert(0, os.path.abspath('.')) でパスを設定する。

extensions

追加する拡張機能の記述。

拡張機能は自作できる。あるいは製作者がネットで公開している。

templates_path
追加のテンプレートを格納するフォルダを設定する。デフォルトでは_tamplatesとなっている。
source_suffix

ソースの記述方法について。.rst(reStructuredText)と.md(MarkDown)で選択できる。

デフォルトでは.rst。前のコンテンツでreStの記述方を延々とメモしといてなんだが、MarkDownの方が簡単かつ一般的かもしれない。だが俺はこのまま突っ走る。さらば!

source_encoding

ソースエンコーディングの指定。デフォルトではコメントアウトされている。

utf-8-sigはBOM付きUTF-8のこと。コメントアウトされているのでUTF-8(BOM無し)が採用されている。

master_doc
マスタードキュメントの名前。最初に生成されるページ。マスタードキュメントには中心となるtoctreeが形成される。
project
プロジェクト名を記入する。
copyright
20XX, 著者名 と記述される。
author

ここにも著者名が入る。

プロジェクトを作成する際に必須だった回答のものがここに記述される。

サイト名などの前にある u は日本語表記にするときのマークアップ。(Pythonの記法)。かっこよく英語のサイト名にするなら特に問題はない。

version, release
バージョン情報が入る。versionとreleaseで使い分けができる。置換構文 |version| で確認できる。
このプロジェクトは |version| です。

このプロジェクトのヴァージョンは 1.0 です。

language
ドキュメントの言語のコード。デフォルトでは enja に直すとインデックス製作の時に幸せかもしれない。
today, today_fmt = '%B %d, %Y'

日付のフォーマット。置換構文 |today| で適応される。

デフォルトでは today が空欄になっているので、 today_fmt%B %d, %Y' が適応されている。

最終更新日は |today| です。

最終更新日は 2019年02月04日 です。

pygments_style
ソースコードのシンタックスハイライトのスタイル。テーマによってはいろいろある…らしい。デフォルトは sphinx
todo_include_todos
todoリストを使用するか否か。
extensions = ['sphinx.ext.todo' ]

として、ソースに

.. todo:: 帰りにネギを買ってくる。

課題

帰りにネギを買ってくる。

デフォルトでは False 。当然ながら todo_include_todos = 'true' としないと作用しない。

html_theme
テーマを記述する。デフォルトで以下のテーマが梱包されている。
  • bacic
  • alabaster
  • sphinx_rtd_theme
  • classic
  • sphinxdoc
  • scrolls
  • agogo
  • nature
  • pyramid
  • haiku
  • traditional
  • epub
  • byzstyle

*バージョン1.3現在

html_theme_options
それぞれのテーマに沿ったオプションの追加。
html_theme_path
テーマを格納したフォルダパス。
html_title
ページタイトルの記述。<title></title>の中に置かれる。
html_short_title
ページタイトルを簡略化する。サイト内で使用される。
html_logo

サイトロゴを設定することができる。

ロゴはサイドバー上部などに設置される。画像ファイルは _static に格納する。設定したサイドバーの幅より大きいと表示されない。

html_favicon
ファビコンを設置する。同名のファイルを _static に格納する。サイズは16×16, 32×32。*2017年現在ではそれより大きくても大丈夫らしい。今使っているのは380*380の画像である。
html_static_path
スタイルシートやスクリプトファイルなどを格納するフォルダのパスを指定する。デフォルトでは _static
html_extra_path
robot.tetや.htaccessなどを格納するフォルダパス。
html_sidebars
カスタムサイドバーのテンプレートパス。
html_use_index
HTMLドキュメントに索引を追加する。デフォルトではTrue。
html_show_sourcelink
サイドバーにソースファイルのリンクを張る。当然のことながらソースがアップされていなければ見ることができない。ソースは.txt
html_show_sphinx
「このドキュメントは Sphinx で生成しました。」という説明がフッターに追加される。デフォルトは True
html_show_copyright
「(C) Copyright 著作名」という文字列がフッターに追加される。デフォルトは True
html_file_suffix
HTMLファイルのファイル名の末尾に追加される文字列を指定する。デフォルトでは .html
html_search_language
HTMLの全文検索インデックスの生成に使用する言語を設定する。デフォルトは en