文書のビルド

ドキュメントの概要

GDALのドキュメントには,Doxygenを使用してソースコメントから自動的に構築されたCおよびC++の API documentation と,手動で編集された内容を含むreStructuredText(rst)ファイルが含まれています.

Sphinx は,上記のコンポーネントを組み合わせて,HTML,PDFおよびその他の形式の完全なドキュメントセットを作成するために使用されます.

Sphinx およびGDALで使用される拡張機能は,``doc``サブディレクトリから python3 -m pip install -r requirements.txt を実行することでインストールできます.

文書のビルド

ドキュメントは,UnixシステムのGDALソースリポジトリの doc サブディレクトリからMakefileターゲットを使用して生成できます.

次のターゲットが利用可能です:

  • html: HTMLドキュメントを doc/build/html ディレクトリにビルドし,ウェブブラウザを使用して表示できます.

  • man: doc/build/man ディレクトリに MANページをビルドします.

  • latexpdf: PDFドキュメントを doc/build/pdf ディレクトリにビルドします

  • doxygen: API Doxygen XMLおよびHTML出力を再生成し, html ターゲットで使用されます.ソースファイルが変更されたときにDoxygenコンテンツが自動的に再構築されないため,このターゲットを明示的に実行して更新する必要があります.

  • doxygen_check_warnings: doxygen と同じですが,Doxygenが警告を出力したときにエラーとなります(doxygen ターゲットはDoxygenの警告に対して寛容です).Doxygenの警告がないことを確認する連続統合チェックの1つを再現するために役立ちます.Doxygen >= 1.9.3 が警告フリーであることが必要です.

  • spelling: ドキュメントのスペルチェックを実行し, C/C++ API(Doxygen)およびPython APIから生成されたドキュメントもカバーします.スペルチェッカーには不明な単語がありますが,それらは有効と見なされるため, doc/source/spelling_wordlist.txt に許可リストに追加する必要があります.

  • clean: doc/build ディレクトリをクリーンアップします.

これらのターゲットをCMakeターゲットとして実行することもできます.その場合,出力ディレクトリはCMakeビルドディレクトリの doc/build サブディレクトリになります.ドキュメントのクリーンアップのみを行うには, clean_doc ターゲットを呼び出すことができます.注意:これらのCMakeターゲットは, CMake BUILD_DOCS=ON 変数が設定されている場合のみ利用可能です(Doxygen,Sphinxおよびmakeが利用可能である場合にはデフォルトで設定されます).

編集中にドキュメントの変更を視覚化するために, sphinx-autobuild pythonパッケージをインストールすると便利です.インストール後, doc``サブディレクトリから ``sphinx-autobuild -b html source build を実行すると,ドキュメントがビルドされ,ローカルウェブサーバで http://127.0.0.1:8000 で提供されます.変更が rst ドキュメントファイルに加えられると,提供されるページは自動的にリフレッシュされます.

Python API ドキュメント

Sphinxは,Python関数のdocstringからPython APIのドキュメントを生成するために autodoc 拡張機能を使用します. autodoc によって正しく解析されるためには,docstringは numpydoc Style guide に従う必要があります.Docstringは2つの場所にあります.関数がPythonで定義された場合(つまり, %pythoncode SWIGディレクティブを使用して定義された場合),docstringは関数定義内に配置する必要があります.関数がC++のみで定義されている場合,docstringはdocstringのみを含む別のファイルに配置する必要があります( docs に配置されています).Sphinxはドキュメントを生成する際にPythonバインディングをロードするため,変更を反映させるためには以下の手順を完了する必要があります:

  • ビルドディレクトリからPythonバインディングを再構築する( cmake --build . --target python_binding )

  • 更新されたPythonバインディングをPythonに表示可能にするために,それらをインストールするか,ビルドディレクトリから scripts/setdevenv.sh を実行します

  • ドキュメントが表示されるページに関連する rst ファイルのタイムスタンプを更新します(例: touch doc/source/api/python/osgeo.ogr.rst)

Sphinx RST スタイルガイド

このセクションには,SphinxとreStructuredTextの使用に関する構文ルール,ヒント,トリックが含まれています.詳細については,この reStructuredTextの包括的なガイド および Sphinx reStructuredText Primer を参照してください.

基本的なマークアップ

reStructuredTextドキュメントはプレーンテキストで書かれています.複雑なフォーマットが必要ないため,プレーンテキストドキュメントのように簡単に構成できます.基本的なフォーマットについては,この表を参照してください:

フォーマット

構文

出力

イタリック

*イタリック* (シングルアスタリスク)

イタリック

太字

**太字** (ダブルアスタリスク)

太字

等幅

`` 等幅 `` (ダブルバッククォート)

等幅

警告

基本的なマークアップの使用は 推奨されません!可能な限り,コマンド,パラメータ,オプション,入力,ファイルを論理的にマークするために,後述のSphinxインラインディレクティブを使用してください.一貫してディレクティブを使用することで,これらの項目を適切にスタイル付けすることができます.

リスト

2種類のリストがあります,箇条書きリストと番号付きリストです. 箇条書きリスト は次のようになります:

  • An item

  • Another item

  • Yet another item

これは次のコードで実現されます:

* An item
* Another item
* Yet another item

番号付きリスト は次のようになります:

  1. First item

  2. Second item

  3. Third item

これは次のコードで実現されます:

#. First item
#. Second item
#. Third item

数字は自動的に生成されるため,アイテムの追加/削除が簡単になります.

リストテーブル

箇条書きリストは時に煩雑で追いにくいことがあります.アイテムの長いリストを扱う場合は,リストテーブルを使用してください.たとえば,オプションのリストについて話す場合,次のようなテーブルを作成します:

Shapes

Description

Square

Four sides of equal length, 90 degree angles

Rectangle

Four sides, 90 degree angles

これは次のコードで行います:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Shapes
     - Description
   * - Square
     - Four sides of equal length, 90 degree angles
   * - Rectangle
     - Four sides, 90 degree angles

ページラベル

すべてのページに,ファイル名と一致するラベルがあることを確認してください. たとえば,ページの名前が foo_bar.rst の場合,ページには次のラベルが必要です:

..  _foo_bar:

他のページは,次のコードを使用してそのページにリンクできます:

:ref:`foo_bar`

リンク

他のページへのリンクは,決して "ここ" というタイトルにすべきではありません.Sphinxは,リンクされたドキュメントのタイトルを自動的に挿入することで,これを簡単にします.

悪い例

リンクに関する詳細は ここ にあります.

良い例

詳細については, リンク のセクションを参照してください.

外部ウェブサイトへのリンクを挿入するには:

`Text of the link <http://example.com>`__

結果のリンクは次のようになります: リンクのテキスト

警告

同じテキストを持つ2つのリンクを持つことは非常に簡単であり,次のエラーが発生します:

**(WARNING/2) Duplicate explicit target name:foo**

これらの警告を回避するために,ダブル __ の使用で匿名リンクが生成されます.

セクション

長いページを分割し, Sphinxが目次を生成するのを助けるためにセクションを使用してください.

================================================================================
Document title
================================================================================

First level
-----------

Second level
++++++++++++

Third level
***********

Fourth level
~~~~~~~~~~~~

注意と警告

メインテキストから目立たせるためにセクションのテキストが有益な場合, Sphinxには2つのボックス,ノートと警告があります.それらは同じように機能し,色が異なります. ただし,すべてに強調を追加すると,強調が効果が低下しますので,注意と警告は控えめに使用する必要があります.

ノートの例です:

注釈

This is a note.

このノートは次のコードで生成されます:

.. note:: This is a note.

同様に,警告の例です:

警告

Beware of dragons.

この警告は次のコードで生成されます:

.. warning:: Beware of dragons.

画像

可能な限り,ドキュメントに画像を追加してください. スクリーンショットなどの画像は,ドキュメントを理解しやすくするための非常に役立つ方法です.スクリーンショットを作成する際には,不要なコンテンツ(ブラウザウィンドウ,デスクトップなど)を切り取るようにしてください.画像のスケーリングは避けてください, Sphinxテーマは大きな画像を自動的にリサイズします. また,画像の下にキャプションを含めると便利です.:

.. figure:: image.png
   :align: center

   *Caption*

この例では,画像ファイルはソースページと同じディレクトリに存在します. そうでない場合,上記のコマンドにパス情報を挿入できます.ルート / は conf.py ファイルのディレクトリです.:

.. figure:: /../images/gdalicon.png

外部ファイル

テキストスニペット,ダウンロード可能なコードの大きなブロック,およびzipファイルやその他のバイナリソースをすべてドキュメントの一部として含めることができます.

サンプルファイルへのリンクを含めるには, download ディレクティブを使用します:

:download:`An external file <example.txt>`

このコードの結果は,標準リンクを生成します 外部ファイル

ファイルの内容を含めるには, literalinclude ディレクティブを使用します:

Example of :command:`gdalinfo` use:

.. literalinclude:: example.txt

gdalinfo の使用例:

Driver: GTiff/GeoTIFF
Size is 512, 512
Coordinate System is:
PROJCS["NAD27 / UTM zone 11N",
    GEOGCS["NAD27",
        DATUM["North_American_Datum_1927",
            SPHEROID["Clarke 1866",6378206.4,294.978698213901]],
        PRIMEM["Greenwich",0],
        UNIT["degree",0.0174532925199433]],
    PROJECTION["Transverse_Mercator"],
    PARAMETER["latitude_of_origin",0],
    PARAMETER["central_meridian",-117],
    PARAMETER["scale_factor",0.9996],
    PARAMETER["false_easting",500000],
    PARAMETER["false_northing",0],
    UNIT["metre",1]]
Origin = (440720.000000,3751320.000000)
Pixel Size = (60.000000,-60.000000)
Corner Coordinates:
Upper Left  (  440720.000, 3751320.000) (117d38'28.21"W, 33d54'8.47"N)
Lower Left  (  440720.000, 3720600.000) (117d38'20.79"W, 33d37'31.04"N)
Upper Right (  471440.000, 3751320.000) (117d18'32.07"W, 33d54'13.08"N)
Lower Right (  471440.000, 3720600.000) (117d18'28.50"W, 33d37'35.61"N)
Center      (  456080.000, 3735960.000) (117d28'27.39"W, 33d45'52.46"N)
Band 1 Block=512x16 Type=Byte, ColorInterp=Gray

literalinclude ディレクティブには,シンタックスハイライト,行番号,スニペットの抽出のためのオプションがあります:

Example of :command:`gdalinfo` use:

.. literalinclude:: example.txt
   :language: txt
   :linenos:
   :emphasize-lines: 2-6
   :start-after: Coordinate System is:
   :end-before: Origin =

ファイルとパスを参照する

ファイルとパスを参照するには,次の構文を使用します:

:file:`myfile.txt`

これは出力します: myfile.txt.

同様にパスを参照することもできます:

:file:`path/to/myfile.txt`

これは出力します: path/to/myfile.txt.

Windowsパスの場合,ダブルバックスラッシュを使用します:

:file:`C:\\myfile.txt`

これは出力します: C:\myfile.txt.

特定のパスやファイル名を参照したい場合:

:file:`{your/own/path/to}/myfile.txt`

これは出力します: your/own/path/to/myfile.txt

GDALソースツリー内のファイルを参照するには,次のようにします:

:source_file:`gcore/gdaldriver.cpp`

これはGitHub上のファイルへのリンクを出力します: gdaldriver.cpp

コードを参照する

クラスを参照するには:

:cpp:class:`MyClass`

メソッドまたは関数を参照するには:

:cpp:func:`MyClass::MyMethod`
:cpp:func:`MyFunction`

Define and reference configuration options

設定オプションを定義するには,次のようにします:

.. config:: OPTION_NAME
   :choices: COMMA, SEPARATED, LIST
   :default: DEFAULT_VALUE
   :since: GDAL.MIN.VERSION

   Narrative about the option.

開くオプション(.. oo::),作成オプション(.. co::),データセット作成オプション(.. dsco::),またはレイヤ作成オプション(.. lco::)を定義するためにも同様の構文を使用できます.

GDAL_CACHEMAX などの設定オプションを参照するには,以下の表の構文を使用してください.

オプションタイプ

構文

設定オプション

 
:config:`option_name`

作成オプション

 
:co:`option_name`

オープンオプション

 
:oo:`option_name`

データセット作成オプション

 
:dsco:`option_name`

レイヤ作成オプション

 
:lco:`option_name`

参照コマンド

次の構文でコマンド( gdalinfo など)を参照します:

:program:`gdalinfo`

コマンドラインオプションに option ディレクティブを使用します:

.. option:: -json

   Display the output in json format.

作成パラメータを文書化するために describe を使用します:

.. describe:: WORLDFILE=YES

   Force the generation of an associated ESRI world file (with the extension .wld).