docstring から PDF を出力し push するたびに Google Drive へ同期させる
TL; DR
-
docstringから PDF 出力される - GitHub Actions から Google Drive に同期
- Push するたびにドキュメントが最新に保たれて ✨𝓗𝓪𝓹𝓹𝔂✨
っていうモノをつくった ↓
Happy で埋め尽くして R.I.P. まで行こうぜ
ドキュメント書きたくないけどドキュメントは必要
日々コードを書いていると、昔書いた処理の内容なんて一週間もしないうちに忘れてしまう。
自分の書いたものでさえままならないのだから、それがチーム開発となると大きな問題として顕在化する。
かといって、ドキュメント書け〜と云われると書きたくなくなるのが怠惰なエンジニアたちの定めである。
誰が読むかもわからない文章を読みやすくわかりやすく書けと言われても、その時点では十分に自分では理解できているつもりなので、どうしても億劫に感じてしまう。
というか、コード以外に向き合う時間をなるべく作りたくないというのが本音だろう。
先任者の引継書がチグハグで困惑する図
書いたはいいが、公開できない
また、せめて慣れ親しんだ Markdown 形式で書けるように Docusaurus,GitBook や docsify を導入しても、今度は「表に出せないドキュメントをどうやってホスティングするのか」という問題も生じる（というかそもそもこれらのツールを活用しても、根本的に「コード以外に向き合いたくない」を解消できていない）。
そりゃあ体力のあるところはそんな些細なことには拘らず、内部向けにサイトを設置するなんて簡単にできるのだろうが、スタートアップやら急造チームやらでは、そこまで知見がないというのが現実といえる。
結局 MS Word や Google Docs に書いて PDF 等で出力して間に合わせる形となり、怠惰なエンジニアたちの心は離れ、知見は散逸し、ドキュメントは永遠に質が上がらない。
色々やっても結局は身内向けだし、貢献として評価されにくい問題
そこで docstring2pdf をつくった
Python には docstring という素晴らしい機能がある。
これを利用してコードを書きながら、ついでに使い方もちょろっとメモ的に書き残して、それがそのままドキュメントになったらいいな〜というのが最初の発想だった。
もちろんこれは先人も思いついていて実装されていたのだが、
- PDF として出力したい
- GitHub Actions で実行して、最新のソースでビルドしたい
- ついでに Google Drive に同期したい
っていう要件が満たされているものはまだなさそうだった（無いよね？）。
こうしていろいろなプラグインやらソフトウェアやらを組み合わせて実現したのが docstring2pdf である。
感想
詳しい使い方とかは、docstring2pdfのページに書いたので、そちらを参照してほしい。
さっそく自分のチームにも新年度から導入し、メンバー全員が docstring も書きつつコードも書きつつ頑張っていこう！というよい感触が得られたのでとても嬉しい。
ぜひ皆様もどうぞ〜😊
新年度もチーム一丸で頑張ろう！
改善点
当然ながら、まだこれだけでは改善すべき点はある。例えば、
- PDF 出力がガタつく
- デザインを変えたい
- フォントもうちょいどうにかしたい
- サービスアカウントじゃなくて
OIDC使って Workload Identity 連携 にしたい - Google Drive 以外のクラウドストレージにも対応したい
などなど…
このあたりのことも、ぜひ Issue に書くとか PR を投げるとか
なにとぞよろしくおねがいしまーす！！ 💪
Discussion