How it works ?¤
大まかに分けると、以下の三段階で機能している：
mkdocstringsでコード内の当該部分を抜き出すMkDocsで静的サイトを生成mkdocs-with-pdfでサイトを PDF 化
mkdocstrings¤
Recipes にもある通り、 さらに他の plugins と組み合わせることによって、 docstring から文書の自動生成を達成している。
これらの組み合わせにより、いちいち別のファイルを経由せずとも
対象の *.py ファイルから抜き出してページを生成できるようになっている。
MkDocs¤
プロジェクトの根幹を成すのが静的サイトジェネレータの一つである MkDocs だ。
ただし、これはあくまでベースとしての利用にとどめており、実際にメインを飾っているのは
Material for MkDocs である。
https://squidfunk.github.io/mkdocs-material
テーマがきれいであることはもとより、様々なカスタマイズができるし、開発も盛んである。 これのおかげで、いま読んでいるこのドキュメントも今風のいい感じの UX を提供できている。
mkdocs-with-pdf¤
mkdocs のプラグインであり、ビルドしたサイトに対し WeasyPrint を
使用して PDF に変換する処理を担う。
https://github.com/orzih/mkdocs-with-pdf
端的に言えば、「これしか見当たらなかった」から採用しているが、 もう少し時間をかければより良いアプローチがあるかもしれない。 メンテされていない風に見えるのが非常に気になるところだが、 代替案が見つけられていない以上仕方がないと半ば諦めている。
mkdocs のプラグインでなくとも、静的サイトを PDF 出力するようなツールについて
別の候補があったら教えてほしい。
GitHub Actions and Google Drive¤
３つの機能の外側には、GitHub Actions によるビルド自動化と
rclone による Google Drive との同期も行われている。
リポジトリに変更があるたびにトリガーされ、
ブランチごとのドキュメントがドライブにアップロードされるという仕組みである。
rclone¤
クラウドストレージ上のファイル管理を行うオープンソースのコマンドライン型プログラムです。 Amazon S3やGoogle Drive、Alibaba Cloud、Dropbox、Megaなど40以上の クラウドストレージサービスに対応しており、ファイルの転送、暗号化、圧縮、分割、バックアップ、 復元、同期、ミラーリング、マイグレーション、ストレージ管理といった様々な機能を具備しています。
cf. https://www.sompocybersecurity.com/column/glossary/rclone
Go 製の OSS で、あらゆるクラウドストレージに対応している。 利用者が世界中にいることもあって、日々の開発はたいへん盛んに行われている。
ストレージごとの公式 API やライブラリを使う以外ではもっとも有名でデファクトなツールである。 基本的には単なる Wrapper CLI なので対象が増えるごとに大きくなりがちなところ、 golang で実装することにより手軽さも速度も実現しているようだ（素直にすごい）。
Next¤
以上を踏まえて、具体的な導入方法についても説明する