[Sphinx] #6 ドキュメント構造化 (中級: 外部ドキュメント連携)

# 前提条件

- 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}

FILE_SUB_HANDSON="${DIR_HANDSON}/main/sub.rst" \
     && echo ${FILE_SUB_HANDSON}
```


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

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


1. 外部ファイルのインクルード
=============================


1.1. 外部ファイルの作成 (パーツドキュメント)
--------------------------------------------

```bash:変数の設定:
FILE_PARTS_DOC='usage-simple.txt'
```

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

EOF
```

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


1.2. includeディレクティブ
--------------------------

includeディレクティブは外部ファイルをreSTフォーマットとしてインクルードします。 
reSTドキュメントのパーツ化に利用します。

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

.. include:: ./usage-simple.txt

EOF
```

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


1.3. 外部ファイルの作成 (ソースコード)
--------------------------------------

```bash:変数の設定:
FILE_SOURCE='_command.sh'
```

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

aws ecs describe-clusters \
     --clusters ${ECS_CLUSTER_NAME}

EOF
```

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


1.4. literalincludeディレクティブ
---------------------------------

literalincludeディレクティブは、外部ファイルをリテラル(reSTフォーマットではないもの)としてインクルードします。 ソースコードなどのインクルードに使います。

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

.. literalinclude:: ./_command.sh
   :language: bash

EOF
```

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


2. 虫食いドキュメント
=====================


2.1. 定義ファイルの作成
-----------------------

```bash:変数の設定:
FILE_DEFINES='defines.txt'
```

```bash:コマンド:
cat << EOF >> ${FILE_DEFINES}
.. |CURRENT_VERSION|    replace:: 1.0.0
.. |AWS_DEFAULT_REGION| replace:: us-west-2
.. |ECS_CLUSTER_NAME|   replace:: sample-cluster
EOF
```

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

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

.. include:: ./defines.txt

- 現在のバージョンは\ |CURRENT_VERSION|\ です。

EOF
```

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


2.2. parsed-literalディレクティブ
---------------------------------


```bash:変数の設定:
FILE_RESULT='_result.template'
```

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

結果(例):

.. parsed-literal::

   {
       "clusters": [
         {
             "status": "ACTIVE",
             "clusterName": "\ |ECS_CLUSTER_NAME|\ ",
             "registeredContainerInstancesCount": 0,
             "pendingTasksCount": 0,
             "runningTasksCount": 0,
             "activeServicesCount": 0,
             "clusterArn": "arn:aws:ecs:\ |AWS_DEFAULT_REGION|\ :XXXXXXXXXXXX:cluster/\ |ECS_CLUSTER_NAME|\ "
         }
       ],
       "failures": []
   }

EOF
```

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

.. include:: ./_result.template

EOF
```

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

完了
======