LoginSignup
4

More than 5 years have passed since last update.

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

Last updated at Posted at 2015-07-20

前提条件

0. 事前作業

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

変数の設定
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

2. 虫食いドキュメント

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

完了

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
4