[Sphinx] #3 基礎編 (ディレクティブ for Web)

# 前提条件

- Sphinxの利用環境が準備できていること
    - 参考: http://qiita.com/tcsh/items/ce758fd45f748463c4b9#%E7%92%B0%E5%A2%83%E6%A7%8B%E7%AF%89-%E5%8F%82%E8%80%83
- ドキュメントプロジェクトを作成してあること
    - http://qiita.com/tcsh/items/b102d70212d97aede46f


0. 事前作業
===========

プロジェクトディレクトリの決定
------------------------------

```bash:変数の設定:
DIR_HANDSON="${HOME}/$( date +%Y%m%d )-handson" \
     && echo ${DIR_HANDSON}

FILE_HANDSON="${DIR_HANDSON}/main/index.rst" \
     && echo ${FILE_HANDSON}
```


プロジェクトディレクトリへの移動
--------------------------------

```bash:コマンド:
cd ${DIR_HANDSON}/main/
```


1. ディレクティブとロール
=========================

## ディレクティブとは (..ではじまるもの)

ブロックレベルで特殊な機能を実現するものです。 

使う頻度は非常に高いです。

```text:ディレクティブの書式:
   .. ディレクティブ名:: オプション
      :引数:
      :パラメータ付き引数: パラメータ

      コンテンツ
```


2. imageディレクティブ
======================

```bash:コマンド:
cp (適当なjpgファイル) ./sample.jpg
```

```bash:コマンド:
cat << EOF >> ${FILE_HANDSON}

.. image:: sample.jpg
  :width: 360

EOF
```

```bash:コマンド(更新):
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html
```


3. rawディレクティブ
====================

```bash:コマンド:

cat << EOF >> ${FILE_HANDSON}

.. raw:: html

  <p>
    <a href="http://www.amazon.com/">link</a>
  </p>

EOF
```

```bash:コマンド(更新):
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html
```


4. note, warningディレクティブ (admonition)
===========================================

```bash:コマンド:
cat << EOF >> ${FILE_HANDSON}

.. note::

  メモ書き


.. warning::

  これはヤバい!!

EOF
```

```bash:コマンド(更新):
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html
```

他に以下の admonition系ディレクティブが定義されています。

* attention

* caution

* danger

* error

* hint

* important

* tip


5. code-block
=============

```bash:コマンド:
cat << EOF >> ${FILE_HANDSON}

.. code-block:: bash

  #!/bin/sh
  ENV=text

.. code-block:: json

  {
       key: "value"
  }
EOF
```

```bash:コマンド(更新):
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html
```


6. テーブル系ディレクティブ
===========================


6.1. tableディレクティブ
------------------------

```bash:コマンド:
cat << EOF >> ${FILE_HANDSON}

.. table:: Truth table for "not"

   =====  =====
     A    not A
   =====  =====
   False  True
   True   False
   =====  =====

EOF
```

```bash:コマンド(更新):
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html
```


6.2. csv-tableディレクティブ
----------------------------

```bash:コマンド:
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
```

```bash:コマンド(更新):
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html
```


6.3. list-tableディレクティブ
-----------------------------

```bash:コマンド:
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
```

```bash:コマンド(更新):
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html
```


6. contents
===========

```bash:コマンド:
cat << EOF >> ${FILE_HANDSON}

.. contents::

EOF
```

```bash:コマンド(更新):
echo '---(ここから)---' \
  && cat ${FILE_HANDSON} \
  && echo '---(ここまで)---'
make html
```


7. reSTではないページ
======================

reSTフォーマットではないファイルは、_staticディレクトリに作成します。

```bash:変数の設定:
FILE_ERROR="_static/error.html"
```

```bash:コマンド(更新):
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
```

```bash:コマンド(更新):
echo '---(ここから)---' \
  && cat ${FILE_ERROR} \
  && echo '---(ここまで)---'
make clean && make html
```

```bash:コマンド:
cat _build/html/_static/error.html
```

```html:結果(例)
<!DOCTYPE html>
<html lang="ja">

<head>
  <meta charset="UTF-8">
</head>

<body>
  <h1>404 File Not Found</h1>
  <p>お探しのページは見つかりません。</p>
</body>
</html>
```




任意: バージョン管理ツールへの登録とコミット
============================================

```bash:コマンド(Mercurialの場合):
hg commit -m 'created repository.' \
  && hg log
```

完了
======