ITエンジニア/デザイナ向けにオープンソースを毎日紹介

記法のシンプルさ、機能そして素の状態でも可読性が高いと言ったこともあって人気のMarkdown。利用範囲がどんどん広がっています。READMEだけでなく、プロジェクトのドキュメントを書く際にも利用してみると良いでしょう。

そうなると単純に一つのMarkdownファイルだけでなく、複数のファイルで構成した分かりやすいドキュメント構成にしたくなるはずです。そこで使ってみたいのがParmです。

ParmはPython製のスクリプトで、parと組み合わせ使います。どちらもインストールはpipでできます。

まずはparのインストールから。

$ pip install par
Downloading/unpacking par
  Downloading par-0.9.5.tar.gz
  Running setup.py egg_info for package par

Installing collected packages: par
  Running setup.py install for par

Successfully installed par
Cleaning up...

続いてparm。

$ pip install parm
Downloading/unpacking parm
  Downloading parm-0.9.1.tar.gz (757kB): 757kB downloaded
  Running setup.py egg_info for package parm

Installing collected packages: parm
  Running setup.py install for parm

    Installing parm script to /usr/local/bin
Successfully installed parm
Cleaning up...

これで準備は完了です。まずプロジェクトフォルダを作成して

parm init
を実行します。

幾つかの質問に答えると必要なファイルが生成されます。
幾つかの質問に答えると必要なファイルが生成されます。

フォルダ構成です。
フォルダ構成です。

index.mdは最初の表示、その内容がintroduction.mdになります。実際の内容を記述するファイルは自由に増やせます。

index.mdの内容です。目次を出力しているだけですが、その内容もMarkdownファイルを指定しているだけです。
index.mdの内容です。目次を出力しているだけですが、その内容もMarkdownファイルを指定しているだけです。

introduction.mdの内容。普通のMarkdownテキストです。
introduction.mdの内容。普通のMarkdownテキストです。

HTMLにする際には

parm make
を実行します。デフォルトではプロジェクトディレクトリ以下にHTMLが生成されますが、別途ディレクトリ指定も可能です(-dオプション)。

生成されたHTMLファイル。まさにソフトウェア向けと言った感じです。
生成されたHTMLファイル。まさにソフトウェア向けと言った感じです。

目次を辿ったところ。左側にメニューも出ています。
目次を辿ったところ。左側にメニューも出ています。

Parmではテーマもサポートされており、BootstrapかSemanticが選択できるようになっています(デフォルトはSemanticです)。その他の機能としてreStructuredTextをサポートしていたり、GitHub Pagesとしての発信も考慮されています。

ツールとしてはシンプルでMarkdownベースでドキュメントを書いてそれをHTMLに変換する上で複数ファイルに分割できるのは便利ではないかと思います。社内の開発ドキュメントして使ってみても良さそうです。

ParmはPython製のオープンソース・ソフトウェア(BSD License)です。

Parm

limodou/parm

 

MOONGIFTの関連記事

コメント

  • DevRel
  • Com2