[Sphinx] #4 基礎編 (ロール for Web)

前提条件

• 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_HANDSON="${DIR_HANDSON}/main/index.rst" \
     && echo ${FILE_HANDSON}

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

コマンド

cd ${DIR_HANDSON}/main/

1. ロールとは

ロール (:で囲まれているもの)

インラインで特殊な機能を実現するものです

使う頻度は高くないですが、使いこなしできるとドキュメントの利便性がかなり向上します。
(クロスリファレンス、ダウンロードなど)

ロールの書式

文字列\ :ロール名:`文字列 <パラメータ>` \文字列

2. ダウンロードリンク

:download:ロールを利用します。

コマンド

touch download.txt

cat << \EOF >> ${FILE_HANDSON}

- :download:`テキストファイルのダウンロード <./download.txt>`

EOF

コマンド(更新)

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

任意: バージョン管理ツールへの登録とコミット

コマンド(Mercurialの場合)

hg commit -m 'created repository.' \
  && hg log

完了