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
- ドキュメントの言語のコード。デフォルトでは
en
。ja
に直すとインデックス製作の時に幸せかもしれない。 - 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
。