BackstageのTechDocsを試す

[Backstage](https://backstage.io/)には[TechDocs](https://backstage.io/docs/features/techdocs/)という機能があり、ソースコード内のMarkdownを[mkdocs](https://www.mkdocs.org/)を使って良い感じで取り込んで表示してくれる。
リポジトリごとの技術文書を管理するのに使えそうなので、ここではその機能を検証する。

なお、今回検証に利用したリポジトリは[こちら](https://github.com/imurata/hello-tanzu-backstage)で公開している。

## TechDocsのインストール・有効化

TechDocsもプラグインで実装されているため、プラグインをインストールする形で機能を有効化する必要があるように思えるが、`npx @backstage/create-app`でBackstageをインストールした場合は自動生成される模様。
そのため特にインストールや有効化は不要である。
別手段で構築して`packages/backend/src/plugins/techdocs.ts`がない場合はTechDocsがインストールされていない可能性が高いので、公式ドキュメントの[こちら](https://backstage.io/docs/features/techdocs/getting-started)を参照して構築する。
ここでは`npx @backstage/create-app`で構築したものとして有効化手順は省略する。


## TechDocsを利用するための準備・設定

デフォルトの`app-config.yaml`で以下の設定が入っており、TechDocs参照時にlocalでドキュメントを自動生成するようになっている。
```yaml
techdocs:
  builder: 'local' # Alternatives - 'external'
  generator:
    runIn: 'docker' # Alternatives - 'local'
  publisher:
    type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
```
そのため、特に設定変更せずにTechDocsを利用することが出来る。
なお、ここでGeneratorがdockerになっているが、このdockerはdocker in dockerで起動するようで、イメージのpullにローカルの認証情報を使ってくれない。そのため会社などで使っていてIPがNATされているような場合は`toomanyrequests`に引っかかるのでGeneratorを`runIn: local`に変更する。
Generatorを`runIn: local`に変更した場合、`mkdocs`コマンドがローカルに存在する必要があるためインストールする。
```
apt install mkdocs
pip install mkdocs-techdocs-core
```
mkdocsのtechdocs-coreプラグインを後で利用するため、合わせてインストールした。

次に適当にリポジトリ内にファイルを用意する。
今回TechDocsのために作ったファイルは以下となる。

```
├── catalog-info.yaml
├── docs
│   └── index.md
└── mkdocs.yml
```
- `catalog-info.yaml`：カタログの定義。ドキュメントのパスを指定する。
- `docs/index.md`：Backstage上に表示させるMarkdown
- `mkdocs.yml`：ドキュメント生成ルールを記載
  
catalog-info.yamlの中身は以下となる。
```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: hello-tanzu-backstage
  annotations:
    github.com/project-slug: imurata/hello-tanzu-backstage
    'backstage.io/kubernetes-label-selector': 'app=hello-tanzu-backstage'
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: experimental
  owner: guests
```
`backstage.io/techdocs-ref: dir:.`は`mkdocs.yml`のパスを指定している。
`dir`は代わりに`url`を指定して外部から取ってくることも出来る。
詳細は[こちら](https://backstage.io/docs/features/techdocs/how-to-guides/#how-to-understand-techdocs-ref-annotation-values)参照。
`index.md`をdocsディレクトリに置いているが、これはmkdocsのデフォルトのパスの仕様によるもので、`mkdocs.yml`を修正することで[変更できる模様](https://backstage.io/docs/features/techdocs/creating-and-publishing#enable-documentation-for-an-already-existing-entity)
`index.md`は日本語およびmermaidの確認も兼ねて以下の内容とした。
````
## markdown sample

サンプル

## mermaid sample

```mermaid
---
title: Animal example
---
classDiagram
    note "From Duck till Zebra"
    Animal <|-- Duck
    note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }
```
````

mkdocs.ymlの内容は以下となる。
```yaml
site_name: 'hello-tanzu-docs'

nav:
  - HomeDir: index.md

plugins:
  - techdocs-core
```
`site_name`は表示されるサイト名、`nav`はナビゲーションバー（サイドバー）に表示する内容となる。
また`plugins`はmkdocsのpluginを指定する。

## 動作確認
このcatalog-info.yamlを利用してカタログを作成すれば自動的にTechDocsが生成されるようになる。
カタログを作成し、`DOCS`タブをクリックする。
![1684145995893.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547981/cf93f3d7-4d99-7042-901b-9b2bc6182809.png)


mermaidは上手く表示されなかったものの、Markdownは上手く生成された。
なお、左サイドバーの`Docs`からも参照できる。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547981/d7323c60-dcf3-092c-c126-9937ec19d230.png)
複数のプロジェクトでドキュメントが分散していても、ここから一元的に確認することが出来る。
技術文書の集約に利用できそうだ。