「reStructuredTextの基礎を学びたい」
「reStructuredTextについて詳細を知りたい」
このような場合には、Docutilsがオススメです。
この記事では、Docutilsについて解説しています。
本記事の内容
- Docutilsとは？
- Docutilsのシステム要件
- Docutilsのインストール
- Docutilsの動作確認
それでは、上記に沿って解説していきます。
Docutilsとは？
Docutilsは、オープンソースのテキスト処理システムです。
プレーンテキストのドキュメントを以下の形式として出力できます。
- HTML
- LaTe
- マニュアルページ
- OpenDocument
- XML
Docutilsにおいて、reStructuredTextパーサとしての機能が特に重要になります。
reStructuredTextは、Markdown（マークダウン）のようなモノです。
Markdownを書けるなら、reStructuredTextも苦労せずに書けるでしょう。
reStructuredTextの記述方法は、次のページで説明されています。
reStructuredText Markup Specification
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
実際、DocutilsはreStructuredTextパーサとして各種ライブラリ・ツールで利用されています。
そのようなライブラリ・ツールには、SphinxやRobot Frameworkがあります。
その意味では、Docutilsは重要なPythonライブラリと言えます。
以上、Docutilsについて説明しました。
次は、Docutilsのシステム要件を説明します。
Docutilsのシステム要件
現時点（2022年4月）でのDocutilsの最新バージョンは、0.18.1となります。
この最新バージョンは、2021年11月24日にリリースされています。
サポートOSに関しては、以下を含むクロスプラットフォーム対応です。
- Windows
- macOS
- Linux
サポート対象となるPythonのバージョンは、以下となっています。
- Python 2.7
- Python 3.5
- Python 3.6
- Python 3.7
- Python 3.8
- Python 3.9
公式では、上記のように表示されています。
しかし、Python 3.7以降を利用しましょう。
その理由は、Python公式開発サイクルにあります。
以下は、Python公式開発サイクルです。
| バージョン | リリース日 | サポート期限 |
| 3.6 | 2016年12月23日 | 2021年12月23日 |
| 3.7 | 2018年6月27日 | 2023年6月27日 |
| 3.8 | 2019年10月14日 | 2024年10月 |
| 3.9 | 2020年10月5日 | 2025年10月 |
| 3.10 | 2021年10月4日 | 2026年10月 |
そもそも、Python自体がPython 3.7以降を利用すべきなのです。
また、現在開発中のDocutils 0.19はPython 3.7以降をサポート対象にしています。
まとめると、Docutilsのシステム要件はPython 3.7以降と言えます。
以上、Docutilsのシステム要件を説明しました。
次は、Docutilsのインストールを説明します。
Docutilsのインストール
検証は、次のバージョンのPythonで行います。
$ python -V Python 3.10.2
まずは、現状のインストール済みパッケージを確認しておきます。
$ pip list Package Version ---------- ------- pip 22.0.4 setuptools 62.0.0 wheel 0.36.2
次にするべきことは、pipとsetuptoolsの更新です。
pipコマンドを使う場合、常に以下のコマンドを実行しておきましょう。
python -m pip install --upgrade pip setuptools
では、Docutilsのインストールです。
Docutilsのインストールは、以下のコマンドとなります。
pip install docutils
Docutilsのインストールは、すぐに終わります。
終了したら、どんなパッケージがインストールされたのかを確認します。
$ pip list Package Version ---------- ------- docutils 0.18.1 pip 22.0.4 setuptools 62.0.0 wheel 0.36.2
Docutilsには、依存するパッケージが存在していません。
そのため、既存環境にも容易に導入できますね。
以上、Docutilsのインストールを説明しました。
次は、Docutilsの動作確認を行います。
Docutilsの動作確認
Docutilsのインストールが成功したら、次のコマンド（スクリプト）が利用可能です。
rst2html.py rst2html5.py rst2man.py rst2odt_prepstyles.py rst2s5.py rst2xml.py rst2html4.py rst2latex.py rst2odt.py rst2pseudoxml.py rst2xetex.py
バージョン確認の際は、次のように実行します。
$ rst2html.py --version rst2html.py (Docutils 0.18.1 [release], Python 3.10.2, on linux)
今回は、次の２種類のドキュメントを作成してみましょう。
- HTMLファイル
- ODTファイル（OpenDocument Text）
そのためには、まずはreStructuredTextでファイルを作成する必要があります。
拡張子はrstでもtxtでもどちらでもOKです。
test.txt
箇条書き - 平安時代 - 鎌倉時代 - 江戸時代
このtext.txtをベースにして、HTML・ODTファイルを作成します。
HTMLファイル
rst2html.py test.txt test.html
上記コマンドを実行します。
そうすると、test.htmlが作成されます。
このHTMLファイルをブラウザで開きます。
test.htmlから、reStructuredTextで記述した箇所を抜粋。
<p>箇条書き</p> <ul class="simple"> <li>平安時代</li> <li>鎌倉時代</li> <li>江戸時代</li> </ul>
ちゃんとhtmlタグとして記述されています。
ODTファイル（OpenDocument Text）
ODTファイルは、ワープロ文書のオープン文書形式になります。
次のソフトウェアで開くことが可能です。
- Microsoft Word
- LibreOffice Writer
- OpenOffice Writer
次のコマンドにより、ODTファイルを作成します。
rst2odt.py test.txt test.odt
上記コマンドを実行します。
そうすると、test.odtが作成されます。
test.odtをLibreOffice Writerで開きます。
問題なくワープロ文書として作成できていますね。
以上、Docutilsの動作確認を説明しました。
