前提条件
- Sphinxの利用環境が準備できていること
- ドキュメントプロジェクトを作成してあること
0. 事前作業
プロジェクトディレクトリの決定
変数の設定
DIR_HANDSON="${HOME}/$( date +%Y%m%d )-handson" \
&& echo ${DIR_HANDSON}
FILE_HANDSON="${DIR_HANDSON}/main/index.rst" \
&& echo ${FILE_HANDSON}
プロジェクトディレクトリへの移動
コマンド
cd ${DIR_HANDSON}/main/
1. ディレクティブとロール
ディレクティブとは (..ではじまるもの)
ブロックレベルで特殊な機能を実現するものです。
使う頻度は非常に高いです。
ディレクティブの書式
.. ディレクティブ名:: オプション
:引数:
:パラメータ付き引数: パラメータ
コンテンツ
2. imageディレクティブ
コマンド
cp (適当なjpgファイル) ./sample.jpg
コマンド
cat << EOF >> ${FILE_HANDSON}
.. image:: sample.jpg
:width: 360
EOF
コマンド(更新)
echo '---(ここから)---' \
&& cat ${FILE_HANDSON} \
&& echo '---(ここまで)---'
make html
3. rawディレクティブ
コマンド
cat << EOF >> ${FILE_HANDSON}
.. raw:: html
<p>
<a href="http://www.amazon.com/">link</a>
</p>
EOF
コマンド(更新)
echo '---(ここから)---' \
&& cat ${FILE_HANDSON} \
&& echo '---(ここまで)---'
make html
4. note, warningディレクティブ (admonition)
コマンド
cat << EOF >> ${FILE_HANDSON}
.. note::
メモ書き
.. warning::
これはヤバい!!
EOF
コマンド(更新)
echo '---(ここから)---' \
&& cat ${FILE_HANDSON} \
&& echo '---(ここまで)---'
make html
他に以下の admonition系ディレクティブが定義されています。
attention
caution
danger
error
hint
important
tip
5. code-block
コマンド
cat << EOF >> ${FILE_HANDSON}
.. code-block:: bash
#!/bin/sh
ENV=text
.. code-block:: json
{
key: "value"
}
EOF
コマンド(更新)
echo '---(ここから)---' \
&& cat ${FILE_HANDSON} \
&& echo '---(ここまで)---'
make html
6. テーブル系ディレクティブ
6.1. tableディレクティブ
コマンド
cat << EOF >> ${FILE_HANDSON}
.. table:: Truth table for "not"
===== =====
A not A
===== =====
False True
True False
===== =====
EOF
コマンド(更新)
echo '---(ここから)---' \
&& cat ${FILE_HANDSON} \
&& echo '---(ここまで)---'
make html
6.2. csv-tableディレクティブ
コマンド
cat << EOF >> ${FILE_HANDSON}
.. csv-table:: Frozen Delights!
:header: "Treat", "Quantity", "Description"
:widths: 15, 10, 30
"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"
EOF
コマンド(更新)
echo '---(ここから)---' \
&& cat ${FILE_HANDSON} \
&& echo '---(ここまで)---'
make html
6.3. list-tableディレクティブ
コマンド
cat << EOF >> ${FILE_HANDSON}
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
* - Treat
- Quantity
- Description
* - Albatross
- 2.99
- On a stick!
* - Crunchy Frog
- 1.49
- | 複数行も
| 書けます。
* - Gannet Ripple
- 1.99
- On a stick!
EOF
コマンド(更新)
echo '---(ここから)---' \
&& cat ${FILE_HANDSON} \
&& echo '---(ここまで)---'
make html
6. contents
コマンド
cat << EOF >> ${FILE_HANDSON}
.. contents::
EOF
コマンド(更新)
echo '---(ここから)---' \
&& cat ${FILE_HANDSON} \
&& echo '---(ここまで)---'
make html
7. reSTではないページ
reSTフォーマットではないファイルは、_staticディレクトリに作成します。
変数の設定
FILE_ERROR="_static/error.html"
コマンド(更新)
cat << EOF >> ${FILE_ERROR}
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
</head>
<body>
<h1>404 File Not Found</h1>
<p>お探しのページは見つかりません。</p>
</body>
</html>
EOF
コマンド(更新)
echo '---(ここから)---' \
&& cat ${FILE_ERROR} \
&& echo '---(ここまで)---'
make clean && make html
コマンド
cat _build/html/_static/error.html
結果(例)
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
</head>
<body>
<h1>404 File Not Found</h1>
<p>お探しのページは見つかりません。</p>
</body>
</html>
任意: バージョン管理ツールへの登録とコミット
コマンド(Mercurialの場合)
hg commit -m 'created repository.' \
&& hg log