[Sphinx][reST][備忘録]Sphinxでドキュメントを書くためreST記法に入門した
あらすじ
Sphinxを導入した時にまとめたreST(reStructuredText)記法をアウトプットしよう。まだリファレンス読み込んでおらず、感覚で使っているところもあるので間違った認識もあるかも…そこは学んだら追記しよう。
参考
基本的にSphinxのサイトに書いてあることを写経してます。
注意
見出しの文字数より少なくならないように上下囲む、とかテーブルは列・行を合わせるとか結構シビアな書き方が求められるのですが……pre記法にしても揃ってない…！
見出し系
間違って覚えていたので、見出し系については[http://d.hatena.ne.jp/kk_Ataka/20120816/1345124098:title]を参照。
- h1見出し
半角イコールで上下を揃えて囲むとh1と同等。
=========================
rst(reStructuredText)解説
=========================[f:id:kk_Ataka:20111203000832j:image]
見出しより長くしても問題ないが、見出しより短いと警告される。(Title underline too short.):
===========================
怒られない
===========================
==
怒られる
==以下の見出しも同様。
- h2見出し
下だけ半角イコールでh2と同等。
<h2>になる
==========[f:id:kk_Ataka:20111203000826j:image]
- h3見出し
ハイフンで上下囲むとh3と同等。
----------
<h3>になる
----------[f:id:kk_Ataka:20111203000827j:image]
- h4見出し
下だけハイフンでh4と同等。
<h4>になる
----------[f:id:kk_Ataka:20111203000828j:image]
リスト系
- 箇条書きリスト
箇条書きリストの項目。ハイフンで定義。
- りんご
- きのこ
- パワーアップ用
- 1UP用
- みかん[f:id:kk_Ataka:20111202231941j:image]
- 数字つきリスト
数字つきリストの項目。数字・アルファベット等と半角の閉じ括弧で定義。
1) りんご
2) きのこ
a) パワーアップ用
i) 毒きのこ
b) 1UP用
3) みかん[f:id:kk_Ataka:20111202231922j:image]
また、閉じ括弧 は . でもよい様子。
- 数字つきリストの項目2
シャープで自動発番してくれる。
#. りんご
#. きのこ
#. パワーアップ用
#. 毒きのこ
#. 1UP用
#. みかん[f:id:kk_Ataka:20111202231923j:image]
- 定義項目
一個改行してインデント。二個改行してインデントすると字下げになる。
キノコ
食べてパワーアップする
スター
一定時間無敵になる[f:id:kk_Ataka:20111202231924j:image]
装飾系
- イタリック体
アスタリスクで囲んでイタリック体。
*アスタリスクで囲んでイタリック体*- ボールド体
アスタリスク2つで囲んでボールド体。
**アスタリスク2つで囲んでボールド体**- そのまま表示
`` ``で囲んだ文字をそのまま表示。アスタリスクで囲んでもイタリック体にならない。
``*囲んだ文字をそのまま表示*アスタリスクで囲んでもイタリック体にならない``- リンク
リンクにしたい文字の後ろ _ をつけ、 別の場所でリンクの定義をする。リンク内にスペースが必要な時は` `でくくる。普通の文字とリンク文字の間にはスペースあけがいるようだ。
リンクその1 ggrks_ と やふれかす_ リンク内にスペースが必要な時はくくる `やふれ かす`_
.. _ggrks: http://www.google.com/
.. _やふれかす: http://www.yahoo.co.jp/
.. _やふれ かす: http://www.yahoo.co.jp/[f:id:kk_Ataka:20111202231925j:image]
- リンクその2
こういう書き方もある。
`グーグル`__ に
__ http://www.google.com/[f:id:kk_Ataka:20111202231926j:image]
- リンクその3
URL直打ちも実はリンクになる。[1]
[f:id:kk_Ataka:20111202231927j:image]
テーブル
半角イコールと半角ハイフンで作れる。イコールで囲んだ行が見出しとなる。
[f:id:kk_Ataka:20111203000829j:image]
[f:id:kk_Ataka:20111202231928j:image]
きちんと列と行を揃える必要がある。これがめんどくさいんだよなあ。なんか楽にテーブル組める方法はないんだろうか。
カラム幅の割合をスペースの量で調整する事もできる。一つ前のテーブルよりも1列目が広い。
[f:id:kk_Ataka:20111203000830j:image]
[f:id:kk_Ataka:20111202231929j:image]
また、半角プラスと半角パイプで枠を作ってテーブルにする事もできる。イコールの上が見出しとなる。これも作るのめんどい？
[f:id:kk_Ataka:20111203000831j:image]
[f:id:kk_Ataka:20111202231930j:image]
文章系
- 基本的な事
途中の改行は無視される。
途中の改行は
無視される[f:id:kk_Ataka:20111202231931j:image]
二行以上改行してからタブで字下げ。タブを戻したら字下げから復帰。
タブでインデントをかけると字下げされる
この行字下げしてます
字下げなおしました[f:id:kk_Ataka:20111202231932j:image]
※二行以上改行してから字下げしないと定義分になる。
※改行してから字下げしないと定義分になる
こんなふうに[f:id:kk_Ataka:20111202231933j:image]
- 整形済みテキスト
文末にコロン2つ。で次の文章をインデントするといわゆるpreタグに。
いわゆる<pre>タグ。今までずっと使ってきてる::
コロン二つのあと字下げで使う？
改行も
字下げも
*文字装飾*も**そのまま表示される**
字下げを戻せば終了- 脚注
脚注は [#]_ で定義。別の場所で脚注の説明。
脚注 [#]_ はこう
連番 [#]_ で触れる
.. [#] ただしイケメンに限る
.. [#] 連番[f:id:kk_Ataka:20111202231934j:image]
[f:id:kk_Ataka:20111202231935j:image]
- 引用
引用は [引用内容] で定義。
引用 [reference]_ はこう
.. [reference] Google先生より[f:id:kk_Ataka:20111202231936j:image]
[f:id:kk_Ataka:20111202231937j:image]
- 置換
|変数|を定義して、 .. |変数| replaceで置換。
ここ置換してね |rep| 。あとここも |rep| ::
.. |rep| replace:: ★ちかん★[f:id:kk_Ataka:20111202231938j:image]
ディレクティブ
- コンテンツ表示
Sphinxページ最上部にコンテンツ一覧を表示できる。:
.. contents::[f:id:kk_Ataka:20111202231939j:image]
- ナビゲーション
スタート > 全ての… > MS > Excel のような表記を表現できる。:
スタート > 全ての... > MS > Excel のような表記を :menuselection:`スタート --> 全ての... --> MS --> Excel` こう表記できる[f:id:kk_Ataka:20111202231940j:image]
Sphinx 初心者
今頃すみません
見出し系について勘違いされているようなので
記号と見出しのレベルの対応は、そのファイル内で出てきた順で決まります。
一番最初に出た形式がh1、次に出た形式がh2、となります。
また、上下に書くのと下に書くのとでは別レベルとして扱われます。
1344825300
kk_Ataka
マニュアルを読み直したらたしかにそのとおりでした。
ご指摘ありがとうございます！
1345123434
[1] これが一番簡単？