reStructuredTextとは？マークアップ言語の特徴と活用方法
1. はじめに
reStructuredText（reST） は、Pythonの公式ドキュメントやSphinxで使用される軽量マークアップ言語です。
Markdownと似た構造を持ちながら、より高度な文書構造をサポート しているのが特徴です。
本記事では、reStructuredTextの基本構文や用途、Markdownとの違い について解説します。
2. reStructuredTextの特徴
2.1. 主な用途
reSTは、以下のような場面で利用されます。
| 用途 | 説明 |
|---|---|
| Python公式ドキュメント | Pythonの公式ドキュメントはreSTで記述 |
| Sphinxを使ったドキュメント生成 | Sphinxを利用してPDFやHTMLを自動生成 |
| ソフトウェアのマニュアル作成 | 開発ドキュメントやAPIリファレンス |
| ブログや記事執筆 | Pelicanなどの静的サイトジェネレーターで使用 |
2.2. Markdownとの違い
| 比較項目 | reStructuredText | Markdown |
|---|---|---|
| 文法の自由度 | 厳格な構造（階層を明確に定義） | シンプルで自由度が高い |
| 拡張性 | Sphinxで拡張可能（PDF、LaTeX、HTML） | 基本的にはHTML変換のみ |
| 表現力 | 脚注、索引、コードブロックの強力なサポート | 基本的なフォーマットのみ |
| 利用シーン | ソフトウェアドキュメント、書籍 | ブログ、GitHub README |
3. reStructuredTextの基本構文
3.1. 見出し
reSTでは、記号の種類と長さで見出しレベルを決定 します。
============= メインタイトル ============= サブタイトル ============ 章のタイトル ------------ 節のタイトル ~~~~~~~~~~~~
3.2. 強調とコードブロック
*イタリック* **ボールド** ``コード``
3.3. 箇条書き
- リストアイテム1 - リストアイテム2 - ネストされたアイテム
3.4. リンク
`Python公式サイト <https://www.python.org/>`_
3.5. 画像挿入
.. image:: sample.png :width: 400px :alt: サンプル画像
3.6. 表（テーブル）
+------------+------------+ | ヘッダー1 | ヘッダー2 | +------------+------------+ | データ1 | データ2 | +------------+------------+
4. SphinxとreStructuredText
Sphinxは、reStructuredTextを用いたドキュメント生成ツール であり、Pythonプロジェクトの公式ドキュメント作成に広く利用されています。
4.1. Sphinxのセットアップ
pip install sphinx
4.2. Sphinxプロジェクトの作成
sphinx-quickstart
4.3. ドキュメントのビルド
make html
Sphinxを使うことで、HTML・PDF・LaTeX など多様なフォーマットで出力可能 になります。
5. まとめ
| ポイント | 内容 |
|---|---|
| reStructuredTextの用途 | Python公式ドキュメント、Sphinx、技術文書 |
| Markdownとの違い | reSTは拡張性と構造化が強み、Markdownは簡潔で使いやすい |
| Sphinxとの連携 | Sphinxを使うとreSTをHTML/PDF/LaTeXに変換可能 |
ソフトウェアのドキュメント作成や技術記事の執筆に最適なreStructuredTextを活用し、より構造化された情報を提供しましょう！
