🔖

Documenter.jlで作る個人サイト

2021.03.28に公開2021.07.23に更新

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

追記① (2021/07/12)

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

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

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

追記② (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にも挙げられていますが、公式には対応していません。

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

Discussion

記事を参考に構築してみました！GitHub pages でHTMLを公開したいのですが，README.mdのみが公開されてしまいます．HTMLを公開するにはどうすれば良いでしょうか．．．

Maybe settings for gh-pages branch?
(nihongo henkan kowaretete, sorry for ro-maji)

ありがとうございます，無事に表示できました！

もう一点すみません，左上いのアイコン(logo.png) はどこで指定していますか？
src見てみたのですがよくわかりませんでした，教えていただけると嬉しいです．

失礼しました，docsを発見しました．(https://juliadocs.github.io/Documenter.jl/stable/man/guide/#Adding-a-logo-or-icon)

Hyrodiumさんの記事を大変参考にさせていただきました．

執筆して公開してくださりありがとうございます！

上手くいったようで良かったです。また何かありましたらコメントお願いします！

ログインするとコメントできます