Qt Contributor Summit 2024: QDocとドキュメントインフラストラクチャチームについて

Qt Contributor Summit 2024 では、私は Nicholas Bennett と共同で、QDoc の最新動向について発表し、ドキュメントインフラストラクチャチームの作業概要を説明しました。 私たちのチームは小規模ですが、Qt の包括的なドキュメントの裏側にあるツールやインフラストラクチャの維持と改善において重要な役割を担っています。この記事では、私の講演の要点をいくつかご紹介します。特に、QDocの最近の進展と今後の計画に焦点を当てます。

ドキュメント インフラストラクチャチームの紹介

私たちのチームは小規模ですが、多様性に富んでいます。開発者とテクニカルライターの両方が所属しています。私はチームのソフトウェアエンジニアで、チームリーダーでありQDocのメンテナンスも担当しているTopi、そしてテクニカルライターのVenu、Andreas、Safiyyah、Jeromeとともに働いています。

私と、管理と開発の両方を担当するTopiというたった1.5人の開発者で作業を行っているため、QDocの開発は思うように進んでいません。最近、チームメンバーの1人がQMLコンパイラチームに異動したため「失って」しまいましたが、もう1人ほどソフトウェアエンジニアが加われば、より多くの作業をより速いペースでこなせるようになるでしょう。

インフラストラクチャ

私たちのチームの主なタスクのひとつは、QtのCI (継続的インテグレーション) システムであるCOINでのドキュメントビルドの管理です。 これによって、ドキュメント関連のアラートをほぼゼロに減らすことができました。また、長年にわたって役立っています。 統合はモジュール単位で行われるため、クロスモジュールのドキュメントビルドはできません。そのため、リンク切れの警告は無視しています。これを緩和するために、毎日スナップショットを実行し、リンク切れの警告や「vale」テキストリンターからの提案などの診断情報を提供しています。これにより、Qtエコシステム全体のドキュメントの品質をより高い水準に維持することができます。

私たちの作業のもう一つの重要な側面は、QDocのビルドに使用されるClangライブラリのプロビジョニングです。これらのライブラリはdownload.qt.ioから入手でき、COINで実行し、インストーラーに同梱するQDocバイナリのビルドに不可欠です。ご自身で QDoc をビルドされる場合は、ご使用のプラットフォームとツールチェーンに対応するパッケージを入手し、リンクすることをお勧めします。プロビジョニングプロセスは、特に最新開発バージョンをCOINで実行中のものと一致させる必要がある場合、難しい場合があります。

QDoc: 最近の進展

私たちのチームは、新しいコマンドから最新の C++ 標準規格への対応まで、いくつかの分野で QDoc の改善に全力で取り組んでいます。

- 新しいコマンド: \fn コマンドのテンプレートオーバーロード解決の改善、\compares および\compareswith コマンドによるC++の型比較結果のドキュメント化、および \details コマンドによるコンテンツの展開など、多数の新しいQDocコマンドや改善されたコマンドを導入しました。\nativetype コマンドは、よりわかりやすく堅牢なドキュメント生成方法を提供するもので、古い\instantiates コマンドに代わるものです。古いコマンドは新しいコマンドに委譲されるため、既存のユーザーには影響がありません。さらに、ブランディングを支援する \tm コマンドが追加されました。

- C++20への準備: C++20への準備の一環として、Clang 15からClang 18に移行しました。一方、Qt 6.8ではClang 17を最低限必要とします。また、Clang の C ベースの API から C++ インターフェイスへの部分的な移行も開始しました。このインターフェイスは引き続き拡張し、言語の最新動向に関連する機能の実装能力を向上させていきます。

- リファクタリングとバグ修正: これらの機能アップデートに加えて、QDoc が長期間にわたって安定性を維持し、保守可能な状態を保つために、リファクタリングとバグ修正に時間を費やしました。また、QDocの信頼性を向上させるため、新しいエンドツーエンドのテストも導入しました。

QDocの今後の展開

将来を見据え、私たちはいくつかの主要分野に焦点を当てています。

- QMLとDOM API: QMLのドキュメント生成に関して、QDocがC++と同等な「機能同等性」を実現することを目標に、AST(抽象構文木)ベースのパーサーから進化するDOM APIへの移行を模索しています。これにより、QMLベースのプロジェクト向けのより完全で一貫性のあるドキュメントが作成できると考えています。

- パフォーマンスの最適化:ドキュメント生成の大幅な高速化を目指し、QDoc での作業をより迅速かつ効率的に行うためのパフォーマンスの改善に積極的に取り組んでいます。

- 新しい C++ 機能のサポート: C++の進化に伴い、QDocが新しい言語機能に追随し続けるよう努めています。これは、Qtが新しいC++規格に移行する際に、最新のドキュメントツールを提供するために不可欠です。Qt自体は当面C++20を必要としないと思われますが、いずれ必要になるでしょう。その時には、QDocも対応できるようにしておく必要があります。

コラボレーションとコミュニティの関与

プレゼンテーション中、今後の開発の可能性について活発な議論が交わされました。Cristianは、エピックで計画されている、または欠けているQDocコマンドを追跡しているかどうか尋ねました。必要に応じて実装することが多いため、追跡はしていません。必要に応じて実装します。Tuukkaは、ビデオドキュメントに関する興味深い指摘を行い、従来のテキストベースのドキュメントを補完するマルチメディアリソースをより多く提供する方法について考えさせられました。

また、KDEコミュニティからも、QDocをドキュメント作成に使用することに関心を示していただいています。QDocはQtと緊密に統合されているため、Doxygenベースの現在のシステムで直面しているいくつかの制限に対処できる可能性があるからです。KDEのNicholas氏によると、DoxygenではQMLドキュメントのサポートが十分ではないため、QDocはKDEにとって貴重なツールになる可能性があるとのことです。このことを聞いて非常に嬉しく思います。移行を支援するために、できる限りのサポートを提供したいと考えています。

まとめ

最後に、QDocは大きな進歩を遂げましたが、まだやるべきことはたくさんあります。最新のC++標準規格への準拠、パフォーマンスの向上、QMLサポートの強化など、Qtエコシステムにとって強力で信頼性の高いツールとなるよう、私たちのチームはQDocの改善に尽力しています。コミュニティからのフィードバック、アイデア、コラボレーションはいつでも歓迎いたします。ご質問やご提案などございましたら、ぜひご連絡ください。

Qt ドキュメントの可能性をさらに広げるため、引き続き対話を続けていきましょう。ご意見は下記にコメントしていただければ幸いです。また、私たちの取り組みに貢献したい方は、直接ご連絡ください。