2019-06-19に更新

既存の Vue アプリケーションに VuePress でユーザーズ・マニュアルを後付する

はじめに

やってみたら試行錯誤するところがいくつかありましたので、自分へのメモ1として残して置こうと思い、大変僭越ではございますがこちらをご利用させていただきました次第です

そういうわけですので本稿はコミュニティへのベスト・プラクティスのご提案などとは程遠く、むしろ私の浅学の結果としての誤解や間違いを多々含むものと存じており、そのような誤謬をみつけられましたら忌憚なくご指摘いただければ大変ありがたい次第です

完成イメージ

既存アプリは対戦相手のポケモンの弱点を調べるアプリです、キー入力なしでポケモンの検索が出来るところが自慢です

関係ないですがカイリュウの中国語名みて衝撃を受けました
おまえ、のリュウじゃなくて、快速のリュウだったのね!いままで何年も誤解しててごめんね

で、 VuePress でこんなかんじの ユーザーズ・マニュアルを作ります

アプリとマニュアルの間の行き来はそれぞれのメニューから行けるようにしておきます

これのなにが問題だったのか

VuePress のドキュメントにも書いてあるとおりに既存アプリ側に docs フォルダをつくってそこで作業を初めてしばらくして「あれ?どうしよう?」と悩んだのが下記の2点です

1. SPA が2つできてしまう

VuePress が なにかドキュメンテーション用のコンポーネントを作ってくれるのであれば、それを既存アプリの route に取り込めば既存アプリの中にドキュメントがいい具合にできるんですけどそうはなっていなくて、VuePress を build すると ドキュメントのSPA ができてしまう んです

既存アプリも、VuePress でつくったドキュメントのアプリも両方とも 独立した router を持った別々の SPA になってしまう、独立した index.htmlが2つできてしまうんですよね ^^;;;
どこに置こう?

2. ドキュメントのアプリケーションのデプロイ先

で、例えばドキュメントのアプリケーションを public の下に /docs に build するようにしておけば、開発中既存のアプリからは /docs という route でリソースとしてドキュメントのアプリが参照できる ます、これはいい感じ
でも、Netlify にデプロイするときはリソースは /dist なのでこっちにドキュメントを build したいんですよね

つまり、開発中とデプロイ先でドキュメントの build 先を切り替えたい

解決策

1.アプリとドキュメントとの行き来の実装

とりあえず、VuePress が作る SPA の index.html とそのリソース群を /docs フォルダにまとめて、既存アプリのリソースとして認識できるフォルダ に置く事にします、そうすればドキュメントは既存アプリからリソースとして認識できます

vue-cli で作ったアプリだとリソースは /public なので、そこに docs というフォルダをつくって build してくれるように vuepress の config.js で設定します

module.exports = {
  title: 'Pokéctiveness2',
  description: 'Pokémon move effectiveness chart.',
  dest: 'public/docs',
  base: '/docs/',
}

で、既存アプリケーションの router.js に /docs へのルートを用意します。router の外への参照なので beforeEnter() をつけてあげるのが味噌だとおもいます

  routes: [
  ...
    {
      path: '/docs',
      name: 'docs',
      beforeEnter() {location.href = '/docs'}
    },
...    

ナビゲーションに追加します
ドキュメントは英語版を /docs に、日本語版を /docs/ja につくってます

export default { data(){ return { wordings: wordings, drawer: false, links: [ {icon: 'home', text: 'Home', route: '/'}, ], doc_links: { en: {icon: '', text: 'How To Use', route: '/docs'}, ja: {icon: '', text: '使い方', route: '/docs/ja'} } } },

同様にドキュメントのリソースとしてアプリケーションの index.html を参照なんてできないというか強引にやったとすると元のアプリに戻らず別のアプリへのジャンプになってしまいます ^^;;;

ここは良いアイデアがでなかったのですが、あきらめてドキュメントのメニューにアプリケーションへの URL を直にいれてしまいます

themeConfig: { sidebar: 'auto', locales: { '/': { nav: [ { text: 'back to App', link: 'https://pokectiveness2.netlify.com/'}, ] }, '/ja/': { nav: [ { text: 'アプリに戻る', link: 'https://pokectiveness2.netlify.com/'}, ] } } },

ただし、VuePress のナビゲーションから外へのジャンプは別タブを開いてしまううので元のアプリにバックしたかんじになりません
これは VuePress の デフォルト・テーマにちょこっと手を入れる ことで、タブを開かないように変更します

2. Netlify への Deploy

Publish directorydist だったとすると、Build command で既存アプリの build の後で VuePress を /dist/docs に build するように --dest オプション付きで vuepress buildを実行します

スクリーンショット 2019-06-06 10.43.14.png

That's it!

これで冒頭のアプリケーションが Netlify にデプロイできました!めでたしめでたし

感想

アドベンチャーウィークで現在絶賛出現中のリリーラの中国語名に違和感を覚えます


  1. 困ってググって何年も前に自分が書いた記事に助けられる(忘れて同じ事をしてる)事が私の場合は実によくあります。認めたくないものだな、老齢ゆえの過ちなどとは ↩︎


Dr. Takeyuki Ueda

Je suis un Japonipais, experimants ingénieur logiciel de mobile et cloud. Ph.D en ingénierie.

Crieitは個人で開発中です。 興味がある方は是非記事の投稿をお願いします! どんな軽い内容でも嬉しいです。
なぜCrieitを作ろうと思ったか

また、「こんな記事が読みたいけど見つからない!」という方は是非記事投稿リクエストボードへ!

こじんまりと作業ログやメモ、進捗を書き残しておきたい方はボード機能をご利用ください!

ボードとは?

関連記事

コメント