1. tetunori_lego

    Posted

    tetunori_lego
Changes in title
+TypeDocの生成物をDocusaurus v2に食わせてdeployしてみた
Changes in tags
Changes in body
Source | HTML | Preview
@@ -0,0 +1,82 @@
+# サマリ
+OSSのAPI Referenceサイトを作るにあたり、TypeScriptからTypeDocを使って、しこしこドキュメントを作っていたのですが、サイト自体をDocusaurus v2で楽して公開したいなーと思ったのでやってみた記事となります。
+なお、実際に下記の様なサイト(API Referenceの部分)がコマンド2発くらいで自動生成→デプロイできるようになります。
+p5.toio - API Reference Site
+https://tetunori.github.io/p5.toio/
+
+# 前提と注意事項
+すでにTypeScriptでビルドできる環境やソースコードがあり、TypeDocも導入済みの環境を想定しています。
+以下は最小手数の導入方法を書いていますが、まずはご自分のサンドボックスリポジトリで色々いじくるのをお薦めします。
+
+# Docusaurus v2概要
+[Docusaurus](https://docusaurus.io/)はOSSのドキュメントサイトを簡単に作ることができるFacebook謹製OSSツールですが、現在正式版のv1と平行して、[いろいろ改良中のv2](https://v2.docusaurus.io/)が公開されています。(2020/05/23時点でまだα版です。v2.0.0-alpha.55)
+今回は試用もかねて新しいバージョンを使ってみました。
+
+# Docusaurus v2をインストールする
+基本は[Docusaurusサイト](https://v2.docusaurus.io/docs/installation)の通りに導入することになります。一発コマンドが用意されているので、こちらで簡単にインストールできます。
+
+```bash
+npx @docusaurus/init@next init website classic
+```
+
+Docusaurus的にはフォルダ名は何でも良いのですが、後に使うツールのために`website`フォルダとしておきます。`classic`はテンプレート名ですが、おまじないと思ってください。
+
+この時点でもうサイトの立ち上げが可能です。一度立ち上げてみましょう。
+
+```bash
+cd website/
+yarn run start
+```
+`live-server`が自動で立ち上がり、ブラウザにテストサイトが表示されたかと思います。Docusaurus v2ではダークモードが標準サポートされていたり、モダンな感じにデザインされていますね。
+![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/542654/ae76675d-96b3-58b4-9bfe-0ae63e97c582.png)
+
+# TypeDocのプラグインをインストールする
+さて、いったんDocusaurusから離れて、開発のルートに戻ります。
+TypeDocではデフォルトの形式ですと、ドキュメントサイトの体裁で出力されます。嫌いではないですが、Global/Module/Class/Interfaceと少々冗長に感じる気がしており、見る方からすると直感的な構成にはなっていないと感じていました。
+そこで、今回はTypeDocの出力をDocusaurus v2フォーマットのMarkdownとして出力してくれるプラグイン、[typedoc-plugin-markdown](https://github.com/tom-grey/typedoc-plugin-markdown)を利用しました。小さいながら、今も活発に開発が続いているリポジトリなようです。
+
+さて、インストールは下記のとおりです。
+
+```bash
+npm install --save-dev typedoc typedoc-plugin-markdown
+```
+
+# Markdownとして書き出し
+完了したら、さっそく、Markdownとして書き出してみましょう。
+
+Docuzaurusへ静的ドキュメントとして読ませるためには、`website/docs`フォルダ以下にmdファイルを配置する必要があります。なので、`typedoc.json`などで出力先を変更しておきます。
+
+```json
+ "out": "website/docs",
+```
+
+あとは、いつもの`typedoc`の設定に加えて、プラグインオプションと、今回のmarkdownテーマオプション`docusaurus2`をそれぞれ付帯して`typedoc`するだけです。
+
+```bash
+typedoc --plugin typedoc-plugin-markdown --theme docusaurus2
+```
+
+このコマンドを実行すると、指定したディレクトリ以下に`html/js`ではなく、mdファイルが並ぶことになります。とても簡単です。と同時に、Docusaurusのサイドバー上のメニュー表示を管轄するファイル`website/sidebar.js`が今回のmdファイルをappendしたうえで更新されます。
+余談ですが、このappend、僕は不要なのでskipしたいのですが、`--skipSidebar`オプションがまだDocusaurus v2には非対応なようで、問答無用に上書きされます。Issueをみると、なんと、[本日付けでPR→修正されている](https://github.com/tom-grey/typedoc-plugin-markdown/pull/124)ので、近日中にリリースされると思います。なので、必要な人は今からオプションをつけておくことをお勧めします。
+
+さて、準備はこれで終わりです。最後にもう一度Docusaurusを立ち上げてみましょう。
+
+```bash
+cd website/
+yarn run start
+```
+
+ちゃんと今回取り込んだドキュメントが表示できるようになっていますね。お疲れさまでした。体裁は・・・そんなに良くないけど、このコマンド数でしかもほぼ自動で変換してくれるなら御の字です!
+![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/542654/1eb6c18f-4bc4-17fd-7563-d95f77b848f3.png)
+
+必要に応じて、不要なファイルは表示しない様`sidebar.js`を編集すると、無事に自分好みの公開が出来るようになります。
+
+# デプロイ
+deployも簡単ですよー。GitHub Pagesなら、下記のコマンドを打てば、自動的に`gh-pages`ブランチにwebサイトとしてデプロイされます。
+
+```bash
+GIT_USER=<user> yarn deploy
+```
+
+Enjoy!
+