[Sphinx] #5 ドキュメント構造化 (初級: 複数ファイルを扱う)

前提条件

• 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. 事前作業

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

変数の設定

DIR_HANDSON="${HOME}/$( date +%Y%m%d )-handson" \
     && echo ${DIR_HANDSON}

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

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

コマンド

cd ${DIR_HANDSON}/main/

1. ラベルとクロスリファレンス

1.1. ラベル

コマンド

mv ${FILE_HANDSON} ${FILE_HANDSON}.org

cat << EOF >> ${FILE_HANDSON}
.. _top:

EOF

コマンド(更新)

cat ${FILE_HANDSON}.org >> ${FILE_HANDSON}

cat ${FILE_HANDSON}

1.2. クロスリファレンス

コマンド

echo "" >> ${FILE_HANDSON}
echo ':ref:`Topへ <top>`' >> ${FILE_HANDSON}
echo "" >> ${FILE_HANDSON}

コマンド(更新)

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

2. toctree

コマンド

cat << EOF >> ${FILE_HANDSON}

----------------------------------------------------------------
サブページ
----------------------------------------------------------------

.. toctree::
   :glob:
   :maxdepth: 2

   ./*

EOF

コマンド(更新)

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

取り込むべきサブページが存在しないので、Warningが1件表示されます。

コマンド

cat _warn.log

3. 編集対象ファイルの決定 (サブページ)

変数の設定

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

コマンド

cat << EOF >> ${FILE_SUB_HANDSON}
.. _sub1:

================================================================
サブページ その1
================================================================

EOF

コマンド(更新)

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

完了