IoT機器のAIエージェントシステムを構築する時、使用するプログラム言語が多岐に渡る。 その時のドキュメント統合化を考えてみました。 まだ完全ではありませんが私の備忘録として載せておきます。 来年、実際実行した後Updateしたいと思います。
使用言語
- Python
- AIエージェント設計
- AWS LambdaやGoogle Function
- Angular/React
- UIとしてのWeb構築用
- TypeScript、HTML、SCSS、JavaScript
- C/C++
- IoT機器のマイコンやSoc制御
- System Verilog
- IoT機器にFPGA搭載した場合
- Device Tree
- IoT機器にLinux搭載する場合
- Rust
- 高速バックエンド開発
- 大規模、高負荷になるまでは使用しないかも
Obsidian
使用する基本の構文は、Markdown形式の編集ソフトObsidian。 Markdownはソフトウェアドキュメント言語として業界標準となっており、GitHub Flavored Markdownが業界標準となっている。 Markdownファイルは.mdで、GitHubのREADME.md等である。 ObsidianはGFMとの非互換性が10%ほどあるが、特殊構文の角括弧２つの[[Wikilinks]]などはファイル名が変更となったら自動更新してくれるので、非互換性を差っ引いても仕事効率が上がるため、Obsidianとした。 ObsidianはOSSでローカルPCにインストールして使うと無料で使える。
ファイル共有するには、GitHubを使うのが最も良いと思う。OSSをつかう場合は、Syncthing (OSS)だが、Syncthing をインストールしているPCの電源がOFFになると共有できない。
Obsidianと同じようなソフトNotionは使いやすいが、Notionのクラウドでしか使えず有償となる。
ドキュメント準備
私の場合、VScodeにCopilot入れてSonnet4でプログラムコード生成して、同時に説明などもObsidian記法で生成してもらっています。 これらは、各コードのファイルでコメントとして概略説明と、詳細説明は関数ごとの説明ファイルに記述しています。
ドキュメント生成
２つのステップがある。
- 各言語を、言語に適したツールでドキュメント生成する。
- Docusarausで統合する。
これでソフト部分はすべて統合ドキュメントになります。 しかし動作などは人で別に記述する必要があります。
- Python
- Sphinx、MkDocs
- Docstringsで記述。 ””” ここに記述 ”””
- Angular/React
- TypeScript
- Typedoc
- HTML、SCSS、JSON
- 不要、Docusaurusで直接読み込み
```htmlや```scssや“`jsonブロックを使って、Obsidian形式で記述。
- TypeScript
- C/C++
- Doxygen
- コメントブロック内に、Doxygen記法の@param, @briefで記述
- System Verilog
- Doxygen
- Device Tree
- DTS-doc
- Rust
- rustdoc
- ///や//!内のコメントで記述
ファイル共有
全てのファイル共有は、やっぱりGitHubを使うのがいいですね。 今やPrivate Repository数も無制限になったので、GItHubを活用するのがいいと思います。
コメント