ドキュメント生成¶

GROMACS のドキュメントの作成¶

現時点では、|Gromacs|のドキュメントには、複数のコンポーネント、フォーマット、およびツールがあり、主な目的は、ウェブサイトとリリースtarボールの両方に、バージョン固有の完全なドキュメントをデプロイすることです。

これはかなり複雑な作業であり、ドキュメントの作成に必要な依存関係が、特にクロスコンパイルの場合、コードの作成を妨げないようにする必要があります。また、コードが正常にビルドおよび実行され、ドキュメントが生成されるようにする必要があります。さらに、manページ形式のドキュメント（およびコマンドライン補完）は、tarボールにバンドルするために、ラップバイナリから作成する必要があります。これにより、機能とドキュメントが常に一致するようにすることができます。

ほとんどの開発者が関心を持つ出力は、通常、ビルドツリー内の docs/html/ サブディレクトリに生成されます。

以下のCMakeオプションの少なくともいくつかを有効にする必要があります。

GMX_BUILD_MANUAL: PDF 参照マニュアルを構築するために、次のオプションが必要です（LaTeXおよびImageMagickが必要です）。詳細は：GMX_BUILD_MANUAL を参照してください。
GMX_BUILD_HELP: オプションで、1) シェル補完を自動的に作成するかどうか、および 2) 既存の man ページをインストールするかどうかを制御します（ただし、インストールする前に、man ターゲットを手動でビルドする必要があります）。詳細は：GMX_BUILD_HELP を参照してください。

webpage CMake ターゲット（下記参照）に、完全な Python パッケージのドキュメントを含めるには、GMX_PYTHON_PACKAGE=ON で CMake を設定し、次の Python パッケージの依存関係をインストールします：python_packaging/gmxapi/requirements.txt:

pip install -r python_packaging/gmxapi/requirements.txt

一部のドキュメントは、クロスコンパイル時にビルドできない場合があります。これは、「gmx」という実行可能ファイルを必要とするためです。

以下の make ターゲットが最も役立ちます:

manual

PDF形式の参照マニュアルを生成します。

man

Sphinx を使用して、ラップされたバイナリから man ページを生成します。

doxygen-all

Doxygen を使用してコードのドキュメントを作成します。

インストールガイド

Sphinx を使用して tarball の INSTALL ファイルを作成します。

webpage-sphinx

GROMACS ウェブサイトに必要なすべてのコンポーネント（インストールガイドとユーザーガイドを含む）を Sphinx で生成します。

webpage

GROMACS の完全なウェブページを作成し、すべての必要な要素を含めます。完了すると、「docs/html/index.html」ですべての内容を参照できます。

リリース tarball からビルドした場合、「SOURCE_MD5SUM」、「SOURCE_TARBALL」、「REGRESSIONTESTS_MD5SUM」、および「REGRESSIONTESTS_TARBALL」という CMake 変数は、md5sum の値と tarball の名前を設定することで、最終的な GROMACS へのデプロイメントに含めるために使用できます。

必要なビルドツール¶

以下のツールは、ドキュメントの一部を構築するために使用されます。CMakeを使用してビルドシステムを設定する前に、これらのツールがインストールされていることを確認してください。

Doxygen: Doxygen は、ソースコードのコメントからドキュメントを抽出するために使用されます。また、Doxygen は Markdown ソースファイルから、ドキュメントの概要コンテンツも生成します。現在、警告なしでビルドするには、バージョン 1.8.5 が必要です。 Doxygen の設定と、ソースコードのドキュメント作成に関する詳細な説明は、別のページにあります: Doxygen の使用。
graphviz (dot): Doxygenのドキュメントでは、graphviz の dot を使用して、一部のグラフを生成しています。このツールは必須ではありませんが、Doxygenのビルド時に利用できない場合、警告が表示され、グラフがドキュメントから除外されます。
mscgen: Doxygenのドキュメントでは、mscgen を使用して、一部のグラフを生成します。 dot と同様に、このツールは必須ではありませんが、利用できない場合、警告が表示され、グラフが生成されなくなります。
Doxygenの問題チェックツール: Doxygenは、いくつかの誤った使用方法や不適切なドキュメントに関する警告を生成しますが、多くの一般的な誤りを検出できません。|Gromacs|は、そのような問題を検出するために、追加のカスタムPythonスクリプトを使用します。これは、ビルドシステム内の``check-source``ターゲットを通じて最も簡単に呼び出すことができます。このスクリプトは、ヘッダーのドキュメントが、ソースコードでの使用と一致しているかどうかを確認します（たとえば、モジュール内の内部ヘッダーが、モジュール外から実際に使用されていないことを確認します）。これらのチェックは、CIで実行されます。カスタムチェッカーの詳細については、別のページ（複数のチェッカーで共通）を参照してください：スクリプトによるソースツリーのチェック.
モジュール間の依存関係グラフ: GROMACS は、コードのモジュール間の #include 依存関係を示す、注釈付きの依存関係グラフを生成するために、カスタムの Python スクリプトを使用します。生成されたグラフは、Doxygen ドキュメントに埋め込まれます: 「モジュール依存関係グラフ」。このスクリプトは、カスタムチェッカーとほとんどの機能を共有しており、同じページでドキュメント化されています: スクリプトによるソースツリーのチェック。

Sphinx: Sphinx：少なくともバージョン 4.0.0 が、reStructuredText ソースファイルからドキュメントの一部を構築するために使用されます。適切なバージョンの sphinx-build とその他の必要な Python パッケージをインストールするには、requirements.txt ファイルを docs リポジトリのディレクトリで使用できます。例：pip install -r docs/requirements.txt
LaTeX: また、グラフィックスファイルの形式を変換するためにImageMagickが必要です。
linkchecker: linkchecker は、:file:``docs/linkcheckerrc ファイルと組み合わせて使用し、ドキュメント内のすべてのリンクが正しく解決されるようにします。
ドキュメントはソースファイルからエクスポートされました: コマンドラインオプション、実行可能ファイルのHTMLドキュメント、およびシェル補完用のドキュメントを生成するために、`gmx`バイナリには、必要な情報をエクスポートするための明示的なC++コードが含まれています。ビルドシステムは、これらのドキュメントアイテムを生成するために、構築された`gmx`バイナリを呼び出すターゲットを提供します。生成されたアイテムは、ソース配布からビルドする場合に不要になるように、ソースタールボールにパッケージ化されます（一般的に、クロスコンパイル環境では動作しないため）。Git配布からビルドおよびインストールするには、明示的な手順が必要です。詳細については、`Doxygenドキュメントにおけるラッパーバイナリ`を参照してください。