Help us understand the problem. What is going on with this article?

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

More than 3 years have passed since last update.

前提条件

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

完了

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away