[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

1. 事前作業
   ===========

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

変数の設定

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}

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

コマンド

cd ${DIR_HANDSON}/main/

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

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

変数の設定

FILE_PARTS_DOC='usage-simple.txt'

コマンド

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

EOF

コマンド(更新)

echo '---(ここから)---' \
     && cat ${FILE_PARTS_DOC} \
     && echo '---(ここまで)---'

1.2. includeディレクティブ

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

コマンド

cat << EOF >> ${FILE_SUB_HANDSON}

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

EOF

コマンド(更新)

echo '---(ここから)---' \
     && cat ${FILE_SUB_HANDSON} \
     && echo '---(ここまで)---'
make html

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

変数の設定

FILE_SOURCE='_command.sh'

コマンド

cat << \EOF >> ${FILE_SOURCE}

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

EOF

コマンド(更新)

echo '---(ここから)---' \
     && cat ${FILE_SOURCE} \
     && echo '---(ここまで)---'

1.4. literalincludeディレクティブ

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

コマンド

cat << EOF >> ${FILE_PARTS_DOC}

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

EOF

コマンド(更新)

echo '---(ここから)---' \
     && cat ${FILE_PARTS_DOC} \
     && echo '---(ここまで)---'
make html

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

2.1. 定義ファイルの作成

変数の設定

FILE_DEFINES='defines.txt'

コマンド

cat << EOF >> ${FILE_DEFINES}
.. |CURRENT_VERSION|    replace:: 1.0.0
.. |AWS_DEFAULT_REGION| replace:: us-west-2
.. |ECS_CLUSTER_NAME|   replace:: sample-cluster
EOF

コマンド(更新)

echo '---(ここから)---' \
     && cat ${FILE_DEFINES} \
     && echo '---(ここまで)---'

コマンド

cat << EOF >> ${FILE_SUB_HANDSON}

.. include:: ./defines.txt

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

EOF

コマンド(更新)

echo '---(ここから)---' \
     && cat ${FILE_SUB_HANDSON} \
     && echo '---(ここまで)---'
make html

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

変数の設定

FILE_RESULT='_result.template'

コマンド

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

コマンド

cat << EOF >> ${FILE_PARTS_DOC}

.. include:: ./_result.template

EOF

コマンド(更新)

echo '---(ここから)---' \
     && cat ${FILE_PARTS_DOC} \
     && echo '---(ここまで)---'
make html

完了