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

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

関連記事(この記事の初版より古い記事はリンクがグレーで表示されます)

  1. 2012/08/16 [reST] [Sphinx] Sphinxの見出しについて学びなおし
  2. 2016/11/30 [Sphinx] [Python] [イベント] PyConJP 2016 in TokyoでSphinxハンズオンのTAをしてきた #pyconjp
  3. 2016/10/31 [Sphinx] Software Design 2016年11月号にSphinxの記事を執筆しました #sphinxjp
  4. 2016/01/19 [Sphinx] [イベント] PyLadiesTokyo #8でSphinxハンズオンのTAをしてきた #sphinxjp
  5. 2015/12/01 [Sphinx] [イベント] SphinxCon JP 2015 で雑用してきた #sphinxjp
  6. 2015/11/01 [Sphinx] [イベント] Sphinxワークショップ@関西で事例紹介とハンズオンTAをしてきた #sphinxjp
  7. 2015/10/13 [Sphinx] [Python] [イベント] PyConJP 2015 in TokyoでSphinxハンズオンのTAをしてきた #pyconjp
  8. 2015/07/13 [Markdown] [reST] [Wiki] 軽量マークアップ言語の歴史をゆるく調べた #sphinxjp
  9. 2014/10/27 [イベント] [Sphinx] SphinxCon JP 2014 で発表してきました #sphinxjp
  10. 2014/08/28 [Sphinx] [Ruby] [イベント] kawasaki.rb #015 でSphinx導入事例の発表をしてきました #kwskrb #sphinxjp
  11. 2014/07/13 [Sphinx] [Ruby] [イベント] kawasaki.rb #013 でSphinx導入事例の発表をしてきました と #011 #012 参加記録 #kwskrb #sphinxjp
  12. 2014/05/28 [Sphinx] WindowsにSphinxのlatexpdfjaができる環境を整えるのに苦戦した話
  13. 2014/05/19 [Sphinx] 「Sphinxをはじめよう」を読んで導入したいと思ったので色々考えてみた2
  14. 2013/10/25 [Sphinx] 「Sphinxをはじめよう」を読んで導入したいと思ったので色々考えてみた
  15. 2013/10/02 [Sphinx] Sphinxのプラグインの作り方を学ぶ