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

[Sphinx] #3 基礎編 (ディレクティブ for Web)

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}

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

コマンド
cd ${DIR_HANDSON}/main/

1. ディレクティブとロール

ディレクティブとは (..ではじまるもの)

ブロックレベルで特殊な機能を実現するものです。

使う頻度は非常に高いです。

ディレクティブの書式
   .. ディレクティブ名:: オプション
      :引数:
      :パラメータ付き引数: パラメータ

      コンテンツ

2. imageディレクティブ

コマンド
cp (適当なjpgファイル) ./sample.jpg
コマンド
cat << EOF >> ${FILE_HANDSON}

.. image:: sample.jpg
  :width: 360

EOF
コマンド(更新)
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html

3. rawディレクティブ

コマンド
cat << EOF >> ${FILE_HANDSON}

.. raw:: html

  <p>
    <a href="http://www.amazon.com/">link</a>
  </p>

EOF
コマンド(更新)
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html

4. note, warningディレクティブ (admonition)

コマンド
cat << EOF >> ${FILE_HANDSON}

.. note::

  メモ書き


.. warning::

  これはヤバい!!

EOF
コマンド(更新)
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html

他に以下の admonition系ディレクティブが定義されています。

  • attention

  • caution

  • danger

  • error

  • hint

  • important

  • tip

5. code-block

コマンド
cat << EOF >> ${FILE_HANDSON}

.. code-block:: bash

  #!/bin/sh
  ENV=text

.. code-block:: json

  {
       key: "value"
  }
EOF
コマンド(更新)
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html

6. テーブル系ディレクティブ

6.1. tableディレクティブ

コマンド
cat << EOF >> ${FILE_HANDSON}

.. table:: Truth table for "not"

   =====  =====
     A    not A
   =====  =====
   False  True
   True   False
   =====  =====

EOF
コマンド(更新)
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html

6.2. csv-tableディレクティブ

コマンド
cat << EOF >> ${FILE_HANDSON}

.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"

EOF
コマンド(更新)
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html

6.3. list-tableディレクティブ

コマンド
cat << EOF >> ${FILE_HANDSON}

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - | 複数行も
       | 書けます。
   * - Gannet Ripple
     - 1.99
     - On a stick!

EOF
コマンド(更新)
echo '---(ここから)---' \
     && cat ${FILE_HANDSON} \
     && echo '---(ここまで)---'
make html

6. contents

コマンド
cat << EOF >> ${FILE_HANDSON}

.. contents::

EOF
コマンド(更新)
echo '---(ここから)---' \
  && cat ${FILE_HANDSON} \
  && echo '---(ここまで)---'
make html

7. reSTではないページ

reSTフォーマットではないファイルは、_staticディレクトリに作成します。

変数の設定
FILE_ERROR="_static/error.html"
コマンド(更新)
cat << EOF >> ${FILE_ERROR}
<!DOCTYPE html>
<html lang="ja">

<head>
  <meta charset="UTF-8">
</head>

<body>
  <h1>404 File Not Found</h1>
  <p>お探しのページは見つかりません。</p>
</body>
</html>
EOF
コマンド(更新)
echo '---(ここから)---' \
  && cat ${FILE_ERROR} \
  && echo '---(ここまで)---'
make clean && make html
コマンド
cat _build/html/_static/error.html
結果(例)
<!DOCTYPE html>
<html lang="ja">

<head>
  <meta charset="UTF-8">
</head>

<body>
  <h1>404 File Not Found</h1>
  <p>お探しのページは見つかりません。</p>
</body>
</html>

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

コマンド(Mercurialの場合)
hg commit -m 'created repository.' \
  && hg log

完了

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