Sphinxでドキュメントを書くためreST記法に入門した

あらすじ

Sphinxを導入した時にまとめたreST(reStructuredText)記法をアウトプットしよう。まだリファレンス読み込んでおらず、感覚で使っているところもあるので間違った認識もあるかも…そこは学んだら追記しよう。

参考

基本的にSphinxのサイトに書いてあることを写経してます。

注意

見出しの文字数より少なくならないように上下囲む、とかテーブルは列・行を合わせるとか結構シビアな書き方が求められるのですが……pre記法にしても揃ってない…！

見出し系

間違って覚えていたので、見出し系についてはSphinxの見出しについて学びなおし - kk_Atakaの日記を参照。

h1見出し

半角イコールで上下を揃えて囲むとh1と同等。

      =========================
      rst(reStructuredText)解説
      =========================

見出しより長くしても問題ないが、見出しより短いと警告される。(Title underline too short.):

      ===========================
      怒られない
      ===========================

      ==
      怒られる
      ==

以下の見出しも同様。

h2見出し

下だけ半角イコールでh2と同等。

      <h2>になる
      ==========

h3見出し

ハイフンで上下囲むとh3と同等。

      ----------
      <h3>になる
      ----------

h4見出し

下だけハイフンでh4と同等。

      <h4>になる
      ----------

リスト系

箇条書きリスト

箇条書きリストの項目。ハイフンで定義。

      - りんご
      - きのこ
              - パワーアップ用
              - 1UP用
      - みかん

数字つきリスト

数字つきリストの項目。数字・アルファベット等と半角の閉じ括弧で定義。

      1) りんご
      2) きのこ
              a) パワーアップ用
                      i) 毒きのこ
              b) 1UP用
      3) みかん

また、閉じ括弧は . でもよい様子。

数字つきリストの項目2

シャープで自動発番してくれる。

      #. りんご
      #. きのこ
              #. パワーアップ用
                      #. 毒きのこ
              #. 1UP用
      #. みかん

定義項目

一個改行してインデント。二個改行してインデントすると字下げになる。

      キノコ
              食べてパワーアップする
      スター
              一定時間無敵になる

装飾系

イタリック体

アスタリスクで囲んでイタリック体。

      *アスタリスクで囲んでイタリック体*

ボールド体

アスタリスク2つで囲んでボールド体。

      **アスタリスク2つで囲んでボールド体**

そのまま表示

`` ``で囲んだ文字をそのまま表示。アスタリスクで囲んでもイタリック体にならない。

      ``*囲んだ文字をそのまま表示*アスタリスクで囲んでもイタリック体にならない``

リンク

リンクにしたい文字の後ろ _ をつけ、別の場所でリンクの定義をする。リンク内にスペースが必要な時は` `でくくる。普通の文字とリンク文字の間にはスペースあけがいるようだ。

      リンクその1 ggrks_ と やふれかす_ リンク内にスペースが必要な時はくくる `やふれ　かす`_
      .. _ggrks: http://www.google.com/
      .. _やふれかす: http://www.yahoo.co.jp/
      .. _やふれ　かす: http://www.yahoo.co.jp/

リンクその2

こういう書き方もある。

      `グーグル`__ に
      __ http://www.google.com/

リンクその3

URL直打ちも実はリンクになる。*1

テーブル

半角イコールと半角ハイフンで作れる。イコールで囲んだ行が見出しとなる。

きちんと列と行を揃える必要がある。これがめんどくさいんだよなあ。なんか楽にテーブル組める方法はないんだろうか。
カラム幅の割合をスペースの量で調整する事もできる。一つ前のテーブルよりも1列目が広い。

また、半角プラスと半角パイプで枠を作ってテーブルにする事もできる。イコールの上が見出しとなる。これも作るのめんどい？

文章系

基本的な事

途中の改行は無視される。

          途中の改行は
          無視される

二行以上改行してからタブで字下げ。タブを戻したら字下げから復帰。

          タブでインデントをかけると字下げされる

                  この行字下げしてます

          字下げなおしました

※二行以上改行してから字下げしないと定義分になる。

              ※改行してから字下げしないと定義分になる
                      こんなふうに

整形済みテキスト

文末にコロン2つ。で次の文章をインデントするといわゆるpreタグに。

        いわゆる<pre>タグ。今までずっと使ってきてる::

                コロン二つのあと字下げで使う？
                改行も
                        字下げも
                *文字装飾*も**そのまま表示される**

        字下げを戻せば終了

脚注

脚注は [#]_ で定義。別の場所で脚注の説明。

    脚注 [#]_ はこう
    連番 [#]_ で触れる

    .. [#] ただしイケメンに限る
    .. [#] 連番

引用

引用は [引用内容] で定義。

    引用 [reference]_ はこう

    .. [reference] Google先生より

置換

変数

を定義して、 ..

変数

replaceで置換。

    ここ置換してね |rep| 。あとここも |rep| ::

    .. |rep| replace:: ★ちかん★

ディレクティブ

コンテンツ表示

Sphinxページ最上部にコンテンツ一覧を表示できる。:

      .. contents::

ナビゲーション

スタート > 全ての... > MS > Excel のような表記を表現できる。:

      スタート > 全ての... > MS > Excel のような表記を :menuselection:`スタート --> 全ての... --> MS --> Excel` こう表記できる

*1:これが一番簡単？

2018年以降の記事はGitHub Pagesに移行しました

あらすじ

参考

注意

見出し系

リスト系

装飾系

テーブル

文章系

ディレクティブ