Documenter.jlで作る個人サイト

2021.03.28に公開

Julia

tech

つくったもの

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

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

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_fileとDocumenter.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が使えてハッピー！