Documenter.jlで作る個人サイト

つくったもの

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

https://hyrodium.github.io/

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

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

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

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

• Julia本体のドキュメント
• Plots.jlのドキュメント
• Documenter.jlのドキュメント
• BasicBSpline.jlのドキュメント

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

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

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

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

• Julia の Documenter.jl でホームページを作成する準備．
• PkgTemplates による Julia パッケージの作り方（前半）
• PkgTemplates による Julia パッケージの作り方（後半）

個人サイトに適用する話

注意：以下の情報は古いです。最新情報には記事下部の追記をご確認ください

本題です。かっこいいので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が使えてハッピー！

追記① (2021/07/12)

Documenter.jlではバージョン管理必須で<github pages url>/devのようなディレクトリを掘ってしまうと本文で説明していましたが、最新のDocumenter.jlではバージョン管理無しにも対応しました。deploydocsするときにキーワード引数で以下のようにnothingを指定すればOKです。

deploydocs(;
    repo="github.com/hyrodium/HelloWorld.jl",
    versions=nothing
)

詳細は以下のPRをご覧ください。

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

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

追記② (2021/07/12)

個人サイトではバージョン管理は不要ですが、日本語/英語もあると嬉しいですね。
そういう訳で追加しました。

• 日本語：https://hyrodium.github.io/ja/
• English：https://hyrodium.github.io/en/

もともとはバージョン切り替えに遣われていた場所でしたが、言語切り替えに置き換えるのに便利でした。

(実は https://hyrodium.github.io にはまだ古いコンテンツが残っています。適当なタイミングでリダイレクトするようにしたいですが、日本語版・英語版の何れにリダイレクトするかを決めるのが面倒で…すこし放置します)

追記③ (2021/07/23)

404ページの追加もやって、古いコンテンツを整理しました。404は本来はDocumenter.jlの標準機能に入っているべきで、こちらのissueにも挙げられていますが、公式には対応していません。

なのでちょっと強引に対応させました。詳細はこちらのコードを確認ください↓

https://github.com/hyrodium/hyrodium.github.io/blob/master/docs/make.jl