Weave.jl で Markdown + Julia の文章をHTMLに変換して自分のホームページで公開しよう

本日は

• Markdown ベースで書いた数学のテキストに Julia の実装をしてその結果をグラフにして出力してその様子をホームページで公開できたらいいねーっていう願いをかなえる方法を Weave.jl というパッケージを使ってかなえます．Weave.jl の README.md を見ると

Supports LaTex, Pandoc, Github markdown, MultiMarkdown, Asciidoc and reStructuredText output

となっています．ここはHTMLの変換を紹介しますが, 他の方法にしたい場合は Weave.jl の公式ドキュメントを読むことにします．

• ユーザーは jmd という拡張子で Markdown の文法で文章を書いて，必要に応じて Julia のコードを追記するだけです．
  Weave.jl が変換時に Julia のコードを実行して Plots.jl が作成したグラフを自動的に貼り付けることができます．これはドキュメント時に生成時に簡易的な動作テストをすることを意味するので，公開したホームページを見た別の人が（著者のコードコピペミス起因からくる）コード動かねぇ・・・のような trivial な問題を解消することができます．

準備

• Julia REPL を開いて Weave.jl パッケージをインストールします．

pkg> add Weave

これだけ

動作確認

Weave.jl のチュートリアルにしたがってサンプルを変換してみましょう．Julia の REPL を起動します

julia> using Weave
julia> # サンプルに記述されている Julia の依存パッケージをインストール
pkg> add Plots DSP
julia> # ではレッツ生成！
julia> weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"),
         out_path=:pwd,
         doctype = "md2html")
julia> # ここで ; を入力して REPL から shell モードに切り替える
shell> ls
FIR_design.html 
julia> # 元に戻る. FIR_desigh.html ができれば良い．手元のブラウザでこれを開いて結果を確認

ここでしていることは

• https://github.com/JunoLab/Weave.jl/blob/master/examples/FIR_design.jmd

を変換しているだけですね．weave 関数のオプションは各自確認してください．例えばキャッシュを有効にしておくと繰り返し変換が必要になる（編集して，変換して表示を確認するなど）のときは変換の時間を短縮できます．

自分で書いてみよう

サンプルは動いた．では，自分で書いたドキュメントを変換するぞー．ここではAtomでする方法を紹介します．VSCodeユーザは必要に応じて公式ドキュメントを見てください．

language-weave の導入

• Julia には Juno というAtomベースのIDEがあるのでそれを使っているユーザーもいるでしょう．同様に Weave.jl を使ったドキュメント生成も補助してくれます．それには language-weave が必要です．uber-juno だけ入れてても language-weave は入らないのでまだ導入していないユーザーは導入してくださいまし．

変換してみよう

適当に jmd を拡張子とするテキストをAtomで開いてMarkdownを書いておきます．Qiitaで普段数式混ざりのドキュメントを書いている人ならばすぐにかけるでしょう（次のセクションの実行結果を参照）．

Cmd+Shift+p でコマンドパレットを開いて Weave: Weave To Html を押します．

そのあと Juno の Julia REPL 上で動作がスタートし変換するログが流れます．

実行結果

はい．このようにしてAtomのなかで左にコードを書いて，右側に結果を確認することができました．

jmd のコードを確認しておく

実は Cmd+shift+enter などで jmd の中にある JuliaのコードブロックをJuliaのソースコードとみなして実行することができます．使い方は Juno でコードを実行するのと違いはないはずです．

例えば

    ```julia
    using Plots
    p = plot(sin)
    plot!(p, cos)
    ```

と書いておけばその実行結果がPlotsのpaneに表示されます．

ホームページに公開

はてなブログ

例えばはてなブログのように HTML ベースで記述してブログをかけるサービスでは生成した .html をそのまま貼り付けて公開ができます．

出力結果

SymPy.jl を用いた単純な線形回帰のお話
SymPy.jl を用いた単純な線形回帰のお話(part2)

github.io

自分のGitHubでホストされるホームページのリポジトリに生成したHTMLをaddして対応するリンクを貼っておくことで閲覧することができます．

• https://terasakisatoshi.github.io/diary/2019/assets/linearRegression/single_regression.html
• https://terasakisatoshi.github.io/diary/2019/assets/linearRegression/multiple_regression.html

変換元になった jmd は 上記リンクの html を jmd に置換したリンクにアクセスすると自動的にダウンロードされて入手できます．

まとめ

• Juliaのコード，その実行結果を混ぜた数学文章を生成する方法を書きました．
• 生成されたHTMLを各自が持っているホームページで公開する方法，生成元のコード入手方法を書きました．
  • 表示の雰囲気がはてなとgithub.ioで違いますが，これはブログのテーマやCSSに寄りますので，別の方法で解決してください．

えー，LaTeX に変換してそれをPDFにして出したいんだけれど？

TeX のテンプレートを用意しておきます．下記 tpl のコメントにありますように Weave.jl が採用する julia_tex.tpl に日本語が化ないようにする黒木さんパッチを充てています．

julia_tex.tpl

%%
%% Taken from 
%% https://github.com/JunoLab/Weave.jl/blob/master/templates/julia_tex.tpl
%%
%% I've applied GenKuroki-san's patch
%% https://gist.github.com/genkuroki/479a1fec113035f05c661675eee8b830
%%


% \documentclass[12pt,a4paper]{article}
\documentclass[12pt,a4paper,xelatex,ja=standard]{bxjsarticle}
% \usepackage[a4paper,text={16.5cm,25.2cm},centering]{geometry}
\geometry{top=1cm, bottom=1cm, left=2cm, right=2cm}
\usepackage{lmodern}
\usepackage{amssymb,amsmath}
\usepackage{bm}
\usepackage{graphicx}
\usepackage{microtype}
\usepackage{hyperref}
\setlength{\parindent}{0pt}
\setlength{\parskip}{1.2ex}

\hypersetup
       {   pdfauthor = { {{{:author}}} },
           pdftitle={ {{{:title}}} },
           colorlinks=TRUE,
           linkcolor=black,
           citecolor=blue,
           urlcolor=blue
       }

{{#:title}}
\title{ {{{ :title }}} }
{{/:title}}

{{#:author}}
\author{ {{{ :author }}} }
{{/:author}}

{{#:date}}
\date{ {{{ :date }}} }
{{/:date}}

{{ :highlight }}

\begin{document}

{{#:title}}\maketitle{{/:title}}

\tableofcontents

{{{ :body }}}

\end{document}

これをどこかに置いておいて weave 関数のtemplateキーワード引数にそのパスをおいておきます．

$ ls
goma.jmd    julia_tex.tpl
$ julia
julia> using Weave
julia> weave(
    "goma.jmd",
    out_path=:pwd,
    doctype="md2pdf",
    template="julia_tex.tpl",
)

実行結果

一応日本語が認識されて表示できますが，添字付きの変数の表示がバグってるんですよね．

どなたかいい感じに修正されたDockerイメージを作ってくださいまし．