Hatena::ブログ(Diary)

kk_Atakaの日記 RSSフィード

2011-12-02

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

あらすじ

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

参考

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

注意

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

見出し系

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

  • 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

*1:これが一番簡単?

Sphinx 初心者Sphinx 初心者 2012/08/13 11:35 今頃すみません 
見出し系について勘違いされているようなので

記号と見出しのレベルの対応は、そのファイル内で出てきた順で決まります。
一番最初に出た形式がh1、次に出た形式がh2、となります。

また、上下に書くのと下に書くのとでは別レベルとして扱われます。

kk_Atakakk_Ataka 2012/08/16 22:23 マニュアルを読み直したらたしかにそのとおりでした。
ご指摘ありがとうございます!

スパム対策のためのダミーです。もし見えても何も入力しないでください
ゲスト


画像認証