ReactiveProperty のドキュメントを MkDocs から VuePress に変えてみたときの作業ログ

PC を修理交換したので ReactiveProperty のドキュメント生成に使ってた MkDocs を再セットアップするのではなく、もっと気軽に導入できる、今後も使い続けれて楽しそうなものはないか？という感じで探したところ VuePress が目についたので以降してみました。

vuepress.vuejs.org

前準備

ブランチを切って空コミットをして Pull Request を作って作業を開始です。

git checkout -b migrate-tovuepress
git commit --allow-empty -m "work in progress"
git push --set-upstream origin migrate-to-vuepress

フォルダー構造とかを変えました。

• 旧 Docs フォルダーは古いドキュメントやプレゼン資料やアイコンが入っていたので Assets に移動しました。
• MkDocs フォルダーに今のドキュメントが入っているので docs フォルダーに移動しました。

導入

node.js が入ってれば以下のコマンドで完了

npm i -g vuepress@next

docs フォルダーに package.json を作って .gitignore もおいて下準備は完成です。

npm init -y

ライセンスやらをなおして scripts に以下のように vuepress のコマンドのショートカットを追加しておきます。

"scripts": {"docs:dev": "vuepress dev docs",
  "docs:build": "vuepress build docs"
}

README.md がエントリーポイントっぽいので index.md からリネームします。

とりあえず動かしてみます。

npm run docs:dev

画像出ない（悲

設定変更

ここを参考に設定ファイルを追加します。

vuepress.vuejs.org

docs/.vuepress/config.jsを追加して以下のようにしました。

module.exports = {
    title: 'ReactiveProperty documentation',
    description: 'Official document for ReactiveProperty(https://github.com/runceel/ReactiveProperty)'}

画像表示問題対処

.から始まる相対パスで書けばいいみたいなので書き直しました。

Before

![New Cross Platform App dialog](images/xf-create-project.png)

After

![New Cross Platform App dialog](./images/xf-create-project.png)

無事画像が出るようになりました。

ナビゲーションバー生成

コンテンツ一覧的なものを出したいです。今のドキュメントは以下のように左にメニューがありますが VuePress で生成したものにはない。

MkDocs で作った方には mkdocs.yml というファイルがあって、そこで指定してたという記憶があるので類似にものを探すことにした。

config.js にデフォルトテーマの設定を書けて、そこで色々できるみたいです。とりあえず Navbar をカスタマイズ。

vuepress.vuejs.org

ということで config.js は以下のようになりました。

module.exports = {
    title: 'ReactiveProperty documentation',
    description: 'Official document for ReactiveProperty(https://github.com/runceel/ReactiveProperty)',
    themeConfig: {
        nav: [{ text: 'Home', link: '/'},
            {
                text: 'Getting started',
                items: [{ text: 'Windows Presentation Foundation', link: '/getting-started/wpf.html'},
                    { text: 'Universal Windows Platform', link: '/getting-started/uwp.html'},
                    { text: 'Xamarin.Forms', link: '/getting-started/xf.html'},
                    { text: 'Avalonia', link: '/getting-started/avalonia.html'},
                ]},
            {
                text: 'Features',
                items: [{ text: 'ReactiveProperty', link: '/features/ReactiveProperty.html'},
                    { text: 'ReactivePropertySlim', link: '/features/ReactivePropertySlim.html'},
                    { text: 'Commanding', link: '/features/Commanding.html'},
                    { text: 'Collections', link: '/features/Collections.html'},
                    { text: 'Work together with plane model layer objects', link: '/features/Work-together-with-plane-model-layer-objects.html'},
                    { text: 'Useful classes which implement IObservable', link: '/features/Notifiers.html'},
                    { text: 'Extension methods', link: '/features/Extension-methods.html'},
                    { text: 'Transfer event to ViewModel from View', link: '/features/Event-transfer-to-ViewModel-from-View.html'},
                ]},
            {
                text: 'Advanced topics',
                items: [{ text: 'Thread control', link: '/advanced/thread.html'},
                    { text: 'Work with await operator', link: '/advanced/awaitable.html'},
                ]},
            { text: 'Samples', link: '/samples.html'},
        ]}}

上に出ました！

C# のシンタックスハイライト

C# のコードを埋め込んでる部分は以下のように書いているのですが

 ```cs
 some code here!
 ```

これだとシンタックスハイライトが効かない（ビルド時に cs なんて知らんよって言われてる) ので csharp に変更しました。 これでシンタックスハイライトもばっちりです。

プルリクをマージ

ということで作成してたプルリクエストをマージして完了。

公開

公式にちゃんと GitHub Pages への公開方法も書いてあるので助かりますね。

vuepress.vuejs.org

ReactiveProperty のドキュメントは https://runceel.github.io/ReactiveProperty/で公開してるのでベースを設定します。

module.exports = {
    base: '/ReactiveProperty/',
    title: 'ReactiveProperty documentation',

そして docs フォルダーにデプロイ用のスクリプトを書いて…

#!/usr/bin/env sh

set -e

rm -rf docs/.vuepress/dist
npm run docs:build

cd docs/.vuepress/dist

git init
git add --all
git commit -m 'deploy'
git push -f https://github.com/runceel/ReactiveProperty.git master:gh-pages

Git Bush で deploy.sh を叩くと無事デプロイされました。

Google Analytics 対応

config.js の title や description の並びに ga で ID を指定するだけ。お手軽。

vuepress.vuejs.org

まとめ

VuePress お手軽でいい感じでした。 テーマを自作したり見た目に凝ろうとすると Vue.js の知識がいりそうですが軽く使うだけならいい感じ。

Vue.js やろうかなぁ。