Documenter.jlで作る個人サイト
つくったもの
Documenter.jlって何ができるんですか?
Juliaのパッケージでドキュメントを作成するためのパッケージです!
Julia関連のドキュメントはDocumenter.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が使えてハッピー!