Python で reStructuredText

Python でドキュメント作成といえば sphinx 、 sphinx といえば reStructuredText ということで今回は reStructuredText の基礎に触れてみます。

参考にしたのはリファレンス替わりにも使えるかなとも思ったのでこちら。
reStructuredText入門 — Sphinx 1.5.6 ドキュメント

最低限、セクション構造・リスト・インラインマークアップ・リテラルブロック・リンクあたりを抑えておけばとりあえず体裁の整ったドキュメントを書くことができそうなので何はともあれやってみました。
書いてみたテキストはこんなやつ。

test.rst

==========
reSTの勉強
==========

段落（パラグラフ）
==================

ここから一段落です。
ここは *強調* です。
ここは **強い強調** です。
ここは ``コードサンプル`` です。
ここまで一段落です。

リスト
======

リスト１
--------

* りんご
* ゴリラ
* ラッパ

リスト２
--------

1. ビール

   1. ラガー
   2. エール

2. ウイスキー

.. _list3:

リスト３
--------

#. 野球
#. サッカー

リテラルコードブロック
======================

以下はコードサンプル ::

    print("code sample")

ここからは通常の段落です。

外部リンク
==========

`グーグルへのリンク`_

.. _`グーグルへのリンク`: https://www.google.com/

内部リンク
==========

リスト３へ戻る list3_

`リスト`_ へ戻る

このファイルを Python で html ファイルへ変換してみる。
変換には docutils ライブラリを使う。
作業用の仮想環境を作ります。
コマンドプロンプトから

py -3 -m venv selfstudy

作成した仮想環境に docutils を入れる。

pip install docutils

変換スクリプトが使えるようになるのでファイルを指定して実行してみる。

rst2html.py C:\resttest\test.rst > C:\resttest\test.html

test.html をブラウザで開くときちんと表示されました。