Documenter.jlで作る個人サイト

3 min read読了の目安(約3000字

つくったもの

https://twitter.com/Hyrodium/status/1345342946938298369

https://hyrodium.github.io/

Documenter.jlって何ができるんですか?

Juliaのパッケージでドキュメントを作成するためのパッケージです!

https://github.com/JuliaDocs/Documenter.jl

Julia関連のドキュメントはDocumenter.jlで作るのが標準になっています。いくつかの例:

Documenter.jlって何をやってるんですか?

内部的には以下のことをやってくれてます。

  • ./docs以下を参照してドキュメントを生成
    • markdownからhtmlを生成
    • 数式にもMathJaxやKaTeXで対応
    • ドキュメント生成時にJuliaの実行も可能
  • GitHub Pages等でのデプロイ
    • TravisとかGitHub Actionsで出来ます。

Documenter.jl自体の使い方は他記事が参考になると思います。

個人サイトに適用する話

本題です。かっこいいのでJuliaパッケージ以外にもDocumenter.jlを使いたくなりますよね!?
似たような考えがdiscourceで議論されてましたが、こちらはJulia以外のパッケージに関する話題。個人サイトは少し事情が異なります。

ともかくやっていきましょう。

前述の通り、Documenter.jlは「Juliaパッケージのドキュメント」に特化したパッケージなので、個人サイトには使いにくい部分があります。具体的には<github pages url>/devのようにディレクトリを掘ってしまう所です。パッケージであればバージョンごとのドキュメント整備は必須ですが、個人サイトには不要ですよね。

結論から言えば、これを修正するにはDocumenter.Writers.HTMLWriter.generate_siteinfo_fileDocumenter.gitrm_copyを以下のように修正すればOKです!

"""
Disable generating siteinfo.js
"""
function Documenter.Writers.HTMLWriter.generate_siteinfo_file(dir::AbstractString, version::AbstractString)
end

"""
Redefine gitrm_copy function to produce <repo>/<docs> instead of <repo>/dev/<docs>
"""
function Documenter.gitrm_copy(src, dst)
    repo_dir = splitdir(dst)[1]

    # --ignore-unmatch so that we wouldn't get errors if dst does not exist
    run(`git rm -rf --ignore-unmatch $(repo_dir)`)
    # git rm also removed parent directories
    # if they are empty so need to mkpath after
    # mkpath(dst)
    mktempdir() do backup
        cp(joinpath(repo_dir,".git"), joinpath(backup,".git"))
        cp(src, repo_dir; force=true)
        cp(joinpath(backup,".git"), joinpath(repo_dir,".git"))
    end
    cd(repo_dir)
end

このように関数の挙動を変更するためだけに、Documenter.jlのリポジトリをクローンして独自拡張して…とやっていくのは余りにも大袈裟です。独自拡張のコードでoverrideするのが一番簡単でしょう。これをやるだけのmoduleがHyrodiumHome.jlです。
将来的にDocumenter.jlのバージョンが変わって、このoverrideが使えなくなる可能性がありますが、Project.toml[compat]が指定可能なので無問題でしょう。

GitHub Actionsで自動でビルド→デプロイも可能ですが、方法は他のパッケージと同様なので説明は省略しようと思います。

まとめ

個人サイトにもDocumenter.jlが使えてハッピー!