Sphinxメモ¶
参考リンク¶
プロジェクトの新規作成¶
以下のコマンドを用いる(Pythonのスクリプトフォルダにパスを通しておくこと)。:
sphinx-quickstart
質問に答えていくとプロジェクトが作成される。 (参考)
プロジェクトのビルド¶
sphinx-quickstartを行うとmake.batが作成されるので、 それを用いて以下のコマンドを実行する:
make.bat html
デフォルトの設定だと、.rstファイルを対象に結果ページを出力する。 デフォルトの設定だと、ルートファイルはindex.rstになる。
デフォルトでは更新のあったファイルのみ再ビルドされる。 ファイル名とか変えた時は、ページ間の整合性を保つために、フルで再ビルドするのがよさそう。 気軽にフルで再ビルドするならビルドフォルダ消すのがいいかな。
また、細かい調整が行いたい場合は sphinx-build を用いる。 (参考)
エスケープ処理をしたい¶
バックスラッシュでエスケープできる。例:
\=============
not section
\============
\**nonono**
インラインリテラルも使える。例:
``インラインリテラル`` の例
インラインリテラル内では、改行、連続したバッククォート以外はそのまま表示される
見出し、階層構造について¶
以下の構文で、文章の見出しと階層構造を表現できる:
================
Section Title 1
================
body 1
-------------------
Section Title 2
-------------------
body 2
Section Title3
=================
body 3
- 見出しは文章の上下に記号を付与する方法と、文章の下部のみに記号を付与する方法の2種類
- 全角文字は2文字として計算し、マークアップする文章よりも長い記号列を記述すること
- 見出しに使える記号は
= - ` : . ' " ~ ^ _ * + #など - 出現順序に沿った階層構造が作成される
インラインディレクティブ?¶
いまいち理解できてないけど、以下のような構文がある:
例1
:exsample: body
例2
'解釈が行われる文字列':role:
*強調* はインタープリテッドテキストにstrong roleを与えてもこのように :strong:`強調` できます。
以下とかが参考になるかも
コメント¶
".." に続く好みのインデントの文字列はコメントとして扱われる。
ただし、".." に続く文字列が、ディレクティブとして扱われる文字列の場合はコメントにならない。
その場合は、".." ののちにすぐに改行を入れることでコメントとして扱える。例:
.. コメントです。
..
|置換定義| ..の後に改行が必要
..
image:: /tetete/tetete.jp
ハイパーリンク¶
以下の構文で実現できる:
`link_name <url>_`
`link_name <url>__`
link_nameを名前として認識させる場合はアンダースコア1つ、 単純にテキストとして表示する場合はアンダースコア2つの方を用いる。 (参考)
画像¶
例:
.. image:: ../img/python.png
画像にリンクを張りたい場合:
.. image:: ../img/python.png
:target: http://python.org
(参考)
ソースコードの表示¶
リテラルコードブロックを用いるのが楽:
リテラルコードブロックの説明::
この部分がリテラルコードブロックになる。
デフォルトではPythonに対応した文字がマークアップされる
リテラルコードブロック用の「::」は段落の末尾に記載することができ、
元の段落に戻るまでがリテラルコードブロックとなる。
また、「::」の前が空白だと「::」は非表示になり、
空白でない場合は「:」として出力される。
この部分はリテラルブロック外となる。
また、他の構文と同様に以下のように「::」単体で使うこともできる (前後の空行を忘れないこと)。
::
この部分はリテラルコードブロック
この部分はリテラルコードブロック外
明示的にマークアップされる言語を指定する場合は、以下を用いる:
.. code-block:: language
Some language code.
デフォルトでマークアップされる言語を変更したい場合、 その他の設定を行いたい場合は こちらを参照
画像を文中に読み込みたい¶
置換機能を使う
文中読み込み例 |srm_1_1| |srm_1_2| みたいな感じで読み込む
.. |srm_1_1| image:: image/srm_v1/emoji_u1f60e.png
:scale: 60
.. |srm_1_2| image:: image/srm_v1/emoji_u1f62d.png
:scale: 60
その他¶
テーマの変更¶
conf.pyのhtml_themeを変更する。
alabasterからbizstyleに変更すると、a ''Reason: TemplateNotFound()'' というエラーが発生した。 alabasterの設定用のhtml_sidebarsについてもコメントアウトしないといけなかったらしい。
テーマの編集¶
デフォルトの設定だと、テンプレートファイルはプロジェクトフォルダ配下の_template -> それぞれのテーマのフォルダの順で検索される。 なので自作のテンプレートを_template配下に配置する事で、出力されるhtmlを調整できる。
自分でインストールしたテーマは site-packages 下に、デフォルトテーマは site-packages\sphinx\themes 下に構成ファイルがある。
これを参考にしながらテーマを編集していく。
根っこのファイルは layout.html なのでこれから見始めることが多い。
編集したいファイルが見つかったら、それをプロジェクト配下の_templateフォルダにコピーし、必要な個所を修正することにより、出力されるhtmlを調整できる。
jinjaテンプレートの継承使ったらもう少しスマートにできるようだ。
(参考)
sphinxというファイル名を使用¶
関係あるか分からないけど、ファイル名にsphinx.rstとしていたらヘッダが英語になってた。 sphinx_memo.rstに修正したら日本語で表示された。 予約語なのかな。