reStructuredtext Cheatsheet
Contents
概要
reStructuredText(rst,reST)の基本は以下の通り。
- 記号を使って構造を作っていく
- 空行やインデント(行頭の空白)にも意味がある。
- 入れ子になったブロック(段落)では内側の文章のインデント(空白の桁数)を統一し、同じ位置(桁)から文章が始まるようにする。
- 同じ構造を作るにも、何種類かの記号を使うことが出来るものがある。その文書内で使う記号に統一が取れていれば、どれでもいい。
文章構造
見出し
- 段落の見出し(HTMLのh1,h2,…相当)には「=」や「-」「#」「*」「^」「~」「”」といった記号を使う。
- 記号と見出しレベルには特定の関係はなく、使用した順番で決定される。
- 見出しの文章の上下にその記号を並べる(上下で囲むイメージ)か、文章の下に記号を並べる(アンダーラインの様なイメージ)は別のレベルとして認識される。
- どちらの場合でも、記号は文章の文字数(バイト数)以上にする必要がある。
例1(Sphinxで説明されているPythonドキュメントの慣例): | |
---|---|
##################
Part
##################
*******************
Chapter
*******************
Section
===========================
Subsection
---------------------------
Subsubsection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Paragraph
"""""""""""""""""""""""""""""""""
|
表構造
Simple Tables
- 主な注意点
- 列の間は2マス以上開ける。
- ラインの長さの正確な制限は不明。以下のルールがありそう。
- 各列はヘッダの要素以上の長さが必要。
- 各列要素の始点はラインの始点と合わせる。
- \ で空白セルを表す。
- 途中でセルを結合すると変更できない感じ(要確認)
- 例
===== =====
col 1 col 2
===== =====
1 Second column of row 1.
2 Second column of row 2.
Second line of paragraph.
Each column must have 4 spaces.
But header and lines can be separated 1 space.
3 - Second column of row 3.
- Second item in bullet
list (row 3, column 2).
\ Row 4; column 1 will be empty.
Row 5 has 1 column.
============
col 1 | col 2 |
---|---|
1 | Second column of row 1. |
2 | Second column of row 2. Second line of paragraph. Each column must have 4 spaces. But header and lines can be separated 1 space. |
3 |
|
Row 4; column 1 will be empty. | |
Row 5 has 1 column. |
CSV Tables
- 主な注意点
- 題名はなくても良い。
- 例
.. csv-table:: title
:header: header1,header2,header3
:widths: 20,25,30
cell1,cell2,cell3
cell3,,cell4
header1 | header2 | header3 |
---|---|---|
cell1 | cell2 | cell3 |
cell3 | cell4 |
List Tables
- 例
.. list-table:: title
:widths: 15 10 30
:header-rows: 1
* - header1
- header2
- header3
* - r1cell1
- r1cell2
- r1cell3
* - r2cell1
- r2cell2
- r2cell3
r2cell3-cont
header1 | header2 | header3 |
---|---|---|
r1cell1 | r1cell2 | r1cell3 |
r2cell1 | r2cell2 | r2cell3 r2cell3-cont |
参考
題名 | URL | 説明 |
---|---|---|
はやわかり reStructuredText | http://www.planewave.org/translations/rst/quickref.html | 個人的には最も簡潔にまとまった説明ではないかと思う。ただし、簡潔なので、基本思想やディレクティブがわかりにくく、この説明だけでは足りなかった。 |
Restructured Text (reST) and Sphinx CheatSheet | http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html | 文法とそれらがどう表示されるかがまとめられている。ただし、個人的には不要な説明や冗長な説明もあったので、このまとめをつくった。リンクは他にも適切なものがあるかも。 |
Online reStructuredText editor | http://rst.ninjs.org//rst/quickref.html | 書いてすぐ表示を確認できるので便利 |
はじめにーTinkererの使い方
やること
- Sphinxインストール
- Tinkererインストール
- bitbucketリポジトリ作成
- bitbucketにアップロード
手順
基本的に参考に書いてある通りなので自分でやってみてハマったポイントなどを注意点に書く。
コマンドあれこれ
オプション
-s,–setup 基本ファイル作成(初期設定で一度だけ実行) -p,–post 記事を作成する。
$ tinker --post 'hoge'
--page | 単独ファイルを作成する |
$ tinker --page 'hoge'
-d,–draft ドラフトを作成する。
$ tinker --draft 'hoge'
ドラフトから投稿に変更
$ tinker --post ./draft/hoge.rst
投稿からドラフトに変更
$ tinker --draft ./yyyy/mm/dd/hoge.rst
-b,–build rstファイルをビルドしてhtmlを作成する。
$ tinker -b
Note
バージョン1.0以降の追記
ドラフトから日付を指定して投稿
$ tinker --date yyyy/mm/dd -p drafts/hoge.rst
注意点
- 自分の環境では日本語名で`tinker -p`が通らない。
- パッチも当ててみたがうまく行かない。まあたかがファイル名なのでとりあえず英語でもいいかなって感じ。
- bitbucketのリポジトリ作成が具体的にどうするかわかりにくかったが、ほんとに<user名>.bitbucket.orgというリポジトリをつくればよいという意味
参考
Tinkererの使い方に関しては、以下が詳しい。
- TinkererでSphinxなブログ環境を構築する
- http://akirakw.github.com/2012/09/12/create_blog_with_tinkerer.html
しかし、上記はGithubでの公開手順のため、自分は使用できない。 公開方法は以下が参考になる。
- Sphinxで作ったドキュメントのホスティング
- http://sphinx-users.jp/cookbook/hosting/index.html#bitbucket-org