MojiMoji

Documentation for MojiMoji.

Welcome to MojiMoji.jl

MojiMoji.jl とは

DemoCards.jl と呼ばれるデモ作成を支援するパッケージを使ったサンプルパッケージである．例えば可視化ライブラリの使い方を表示するためのデモページとして使える.

Why MojiMoji

デモのデモなのでメタい感じがする. でもでも・・・って言ってると恥ずかしがってもじもじする様子を連想するのでこの名前を使った．

試す.

`docs/make.jl` の初期化

PkgTemplates.jl などで MojiMoji.jl パッケージを作ると下記のような docs/make.jl が得られる.

using MojiMoji
using Documenter

DocMeta.setdocmeta!(MojiMoji, :DocTestSetup, :(using MojiMoji); recursive=true)

makedocs(;
    modules=[MojiMoji],
    authors="YourName <YourEmail> and contributors",
    repo="https://github.com/<YourGitHubAccount>/MojiMoji.jl/blob/{commit}{path}#{line}",
    sitename="MojiMoji.jl",
    format=Documenter.HTML(;
        prettyurls=get(ENV, "CI", "false") == "true",
        canonical="https://<YourGitHubAccount>.github.io/MojiMoji.jl",
        edit_link="main",
        assets=String[],
    ),
    pages=[
        "Home" => "index.md",
    ],
)

deploydocs(;
    repo="github.com/<YourGitHubAccount>/MojiMoji.jl",
    devbranch="main",
)

<YourGitHubAccount>, <YourEmail> などは各自の環境に依存する．適宜読み替えてほしい. 我々はこの雛形を初期状態として DemoCards の機能を使うために docs/make.jl を編集する.

ローカル環境でドキュメントの閲覧できるか確認

下記を実行する

$ cd path/to/MojiMoji.jl
$ julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
$ julia --project=docs/ docs/make.jl

localhost:8000 にアクセスして適当なWebページが確認できれば成功だ.

Demo 用のファイルを格納するディレクトリの作成

docs/myexamples というデモ用のファイルを格納するディレクトリを作る. このディレクトリ直下に index.md を作成する.

この index.md というファイルの中には {{{democards}}} という文字を挿入する必要がある. この 波括弧 {} で囲む文法はテンプレートエンジン Mustache.jl を利用するためのものである. 実際, DemoCards.jl はデモカードを生成する際にこのテンプレートエンジンを使っている. ユーザーはとりあえずそういうものを入れれば良い程度の感覚を持っていれば良い. ちなみにこのテンプレートエンジンは PkgTemplates.jl でも採用されている.

`docs/make.jl` の更新

下記のように docs/make.jl を更新する.

using MojiMoji
using DemoCards
using Documenter

DocMeta.setdocmeta!(MojiMoji, :DocTestSetup, :(using MojiMoji); recursive=true)

myexamples, myexamples_cb, myexamples_assets = makedemos("myexamples")
assets = collect(filter(x->!isnothing(x), Set([myexamples_assets])))

makedocs(;
    modules=[MojiMoji],
    authors="<YourName> <YourEmail> and contributors",
    repo="https://github.com/<YourGitHubAccount>/MojiMoji.jl/blob/{commit}{path}#{line}",
    sitename="MojiMoji.jl",
    format=Documenter.HTML(;
        prettyurls=get(ENV, "CI", "false") == "true",
        canonical="https://<YourGitHubAccount>.github.io/MojiMoji.jl",
        edit_link="main",
        assets=assets,
    ),
    pages=[
        "Home" => "index.md",
        myexamples,
    ],
)

myexamples_cb()

deploydocs(;
    repo="github.com/<YourGitHubAccount>/MojiMoji.jl",
    devbranch="main",
)

やっていること

using DemoCards を追記した.
makedemos 関数を呼び出す. 引数の "myexamples" は docs/ を起点としたデモを格納した相対パスである.

myexamples, myexamples_cb, myexamples_assets = makedemos("myexamples")

assets 変数を定義する. デモカードのサムネ画像に関する情報を渡すために使われる

assets = collect(filter(x->!isnothing(x), Set([myexamples_assets])))

makedocs 関数のキーワード引数 format に渡す値を下記のようにする. 先ほど定義した assets を Documenter.HTML の assets 引数に渡すだけである.

    format=Documenter.HTML(;
        prettyurls=get(ENV, "CI", "false") == "true",
        canonical="https://<YourGitHubAccount>.github.io/MojiMoji.jl",
        edit_link="main",
        assets=assets,
    ),

myexamples_cb() を呼ぶ. これは makedemos 関数の２番めの戻り値で得たコールバック関数を実行している. DemoCards.jl を利用するためのお作法だと思えば良い. makedocs の後に実行する.

動作確認

julia --project=docs/ docs/make.jl を実行する. 読者が私の MojiMoji.jl を見ている場合は make web とすればコンテナ環境でサーバーを立てて http://0.0.0.0:8000/myexamples/index.html にアクセスすると Demos というページが生成されているはずだ.