reStructured Text (rst) のファイルからHTMLを生成する方法

本ページでは reStructured Text (rst) からHTMLファイルを生成する方法について説明します。

方法 #

rst2html5.py というコマンドを利用して変換を実行します。

まず docutils を導入します。

pip install docutils

rst2html5.py というコマンドが利用できるようになるので、このコマンドで変換します。

rst2html5.py <rstファイル> <出力ファイル>

出力ファイルを指定しない場合、 stdout に出力されます。

説明 #

reStructured Textは docutils のサイトで仕様が公開されている軽量マークアップ言語です。

一般的にはドキュメント作成用ソフトウェアである Sphinx で利用されている言語、という認識をされているように思われます。

実例 #

試しに以下のファイルを作成し、HTMLに変換してみます。

==============
The test file
==============

The 1st heading
================

The 1st paragraph of the 1st header.

The 2nd level heading
----------------------

This is the 1st pragraph in the 2nd level heading.

The 3rd one
~~~~~~~~~~~

You are merely seeing 3rd level.

.. Note::
    You can write a note ...

    to inform something.

`Google <http://www.google.com>`_

List:

* 1
* 2
* 3

.. code-block:: python

    def main(data: str):
        print(data)

これを test.rst として保存し、単純に変換してみます。

rst2html5.py test.rst test.html

そのファイルを表示すると以下のようになります。

それなりに見れる見た目にはなっているようです。

オプション探索 #

オプションを下記コマンドで見ることができます

rst2html.py --help

非常に多くのオプションがありますが、代表的なものを説明します。

オプション	説明
--link-stylesheet	デフォルトではHTMLの中にCSSを書きこむが、このオプションをつけるとリンクで済ませるようになる。
--toc-top-backlinks	見出しをクリックするとTOC(Table of contents; 見出し)に戻るようにする
--stylesheet=<URL>	外部のスタイルシートを設定する場合ここにURLを指定します。
--stylesheet-path=<Path>	外部のスタイルシートを設定する場合ここにファイルパスを指定します。
--syntax-highlight=[option]	Syntax highlightの際に付与するクラス名を長くする ( long ) か短くする (short ) かなど指定できます。こういうところにあるPygmentのCSS などを利用する際には short 前提で記載されているので short にしておいた方がよい。

個人的な感想 #

実は当サイトは rst ファイルをHTMLに変換して作成しているので、その際に docutils を利用しています。

ただ、綺麗な表示をするCSSなどがあまり見つからないので特別な用がない限りは Sphinx などを利用した方が無難です。Sphinxには様々なテーマが準備されており、デフォルトで使ってもかなり見やすいドキュメントを生成できます。

rst ファイルは Markdown よりも記述が面倒なために流行らないのだと思いますが、その分テキストエディタで見た際の視認性の良さは Markdown よりも秀でていると思っています。

みんなも rst、使おう!