BackstageのTechDocsを試す

BackstageにはTechDocsという機能があり、ソースコード内のMarkdownをmkdocsを使って良い感じで取り込んで表示してくれる。
リポジトリごとの技術文書を管理するのに使えそうなので、ここではその機能を検証する。

なお、今回検証に利用したリポジトリはこちらで公開している。

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

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

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

デフォルトのapp-config.yamlで以下の設定が入っており、TechDocs参照時にlocalでドキュメントを自動生成するようになっている。

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の中身は以下となる。

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を指定して外部から取ってくることも出来る。
詳細はこちら参照。
index.mdをdocsディレクトリに置いているが、これはmkdocsのデフォルトのパスの仕様によるもので、mkdocs.ymlを修正することで変更できる模様
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の内容は以下となる。

site_name: 'hello-tanzu-docs'

nav:
  - HomeDir: index.md

plugins:
  - techdocs-core

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

動作確認

このcatalog-info.yamlを利用してカタログを作成すれば自動的にTechDocsが生成されるようになる。
カタログを作成し、DOCSタブをクリックする。

mermaidは上手く表示されなかったものの、Markdownは上手く生成された。
なお、左サイドバーのDocsからも参照できる。

複数のプロジェクトでドキュメントが分散していても、ここから一元的に確認することが出来る。
技術文書の集約に利用できそうだ。