カスタムページ

Doxygenは、ライブラリ/プログラムのAPIの一部ではないカスタムページを作成するためにも使用できます。このようなページの目的は、ユーザーが役立つと思うその他の情報でドキュメントを充実させることです。

カスタムページを作成するには、サポートされているファイル拡張子のいずれかを使用します。.dox、.txt、または.mdです。Doxygenは、.doxまたは.txtファイルをC/C++ソースファイルとして扱い、.mdファイルをMarkdownファイルとして扱います。

.doxまたは.txtファイルの場合、次のように単一のDoxygenコメントを使用できます。

manual/index.dox

/** \mainpage マイライブラリマニュアル
- ビルド
- 基本
- 例
*/

\mainpageコマンドが使用されていることに気づくでしょう。これは、Doxygenにこのページをメインページとして使用するように指示します。他のページでは、\pageコマンドをプレフィックスとして付けます。

デフォルトではDoxygenはこれらのカスタムファイルを知らないので、DoxyfileのINPUT属性を介してDoxygenに知らせる必要があります。上記例の場合、この行をDoxyfileに追加します。

INPUT = manual/index.dox

次に、プロジェクトのビルド方法に関する手順を追加したいので、manual/building/index.doxを作成します。ドキュメントをさらに読み進めると、DoxygenがHTMLタグのサブセットをサポートしていることがわかるので、次のように記述できます。

/** \page ビルド
 
<h2>Linux</h2>
<p>
このプロジェクトをビルドする簡単な方法はcmakeを使用することです。リポジトリをクローンし、プロジェクトのルートにcdして、次を実行します。
</p>
 
<pre>
<code>
mkdir my_build
cmake -S . -B my_build
cd my_build
cmake --build .
</code>
</pre>
 
*/

もちろん、人気のあるMarkdown記法を使用して同じことを行うこともできます。

# Building

## Linux

A simple way to build this project is with cmake, clone the repository,
cd into the root of the project and run:

    mkdir my_build
    cmake -S . -B my_build
    cd my_build
    cmake --build .

スケールアップ

ファイルの自動追加

この時点で、manual/building/index.doxをカンマ区切りでINPUTに追加することもできますが、マニュアルを作成していくうちにこれは煩わしくなる可能性があります。代わりに、マニュアルフォルダを参照するように変更します。

INPUT = manual/

そして、次を設定します。

RECURSIVE = YES

これにより、より多くの構成やコンテンツを作成する際に、マニュアルのサブディレクトリが追加されるようになります。

サイドパネルのツリービュー

マニュアルがスケールアップすると、整理された状態を保つために、マニュアル内の現在位置を示す優れたツリービューも必要になる場合があります。これは簡単に設定できます。

GENERATE_TREEVIEW = YES

Doxyfileで有効にします。

manual/index.doxファイルが、どこにもリンクがない非常に素っ気ないものであることを思い出すでしょう。\refコマンドを使用すると、さまざまなトピック間にリンクを追加でき、そうすることでツリービューが自動的に作成され始めます。

ツリーが葉の山のように見える場合は、サブページをチェックすることでこれを修正できます。

この議論は、ドキュメントを充実させるためのスケーラブルなマニュアルを構築する方法についていくつかの方向性を示すはずです。ここから、レイアウトをカスタマイズしたいと思うかもしれません。

目次

カスタムページ

スケールアップ

ファイルの自動追加

サイドパネルのツリービュー