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

Tags: [ Sphinx ] [ reST ] [ 備忘録 ] Published: 2011/12/02

あらすじ

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

参考

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

注意

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

見出し系

間違って覚えていたので、見出し系については2012-08-16-1345124098を参照。

  • 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: これが一番簡単?

blog comments powered by Disqus

Author: kk_Ataka / Powered by Jekyll on GitHub Pages