RFC104: add documentation

doc/.gitignore

@@ -1,5 +1,4 @@
-build/
+build
+data
 source/drivers/raster/driver_summary.rst
 source/drivers/vector/driver_summary.rst
-source/user/configoptions_index_generated.rst
-.doxygen_up_to_date

doc/source/conf.py

@@ -12,6 +12,7 @@
 #
 import datetime
 import os
+import shutil
 import sys
 
 sys.path.insert(0, os.path.abspath("_extensions"))
@@ -185,6 +186,57 @@
 author_tamass = "Tamas Szekeres <szekerest@gmail.com>"
 
 man_pages = [
+    # New gdal commands and subcommands
+    (
+        "programs/gdal",
+        "gdal",
+        "Main gdal entry point",
+        [author_evenr],
+        1,
+    ),
+    (
+        "programs/gdal_info",
+        "gdal-info",
+        "Get information on a dataset",
+        [author_evenr],
+        1,
+    ),
+    (
+        "programs/gdal_raster",
+        "gdal-raster",
+        "Entry point for raster commands",
+        [author_evenr],
+        1,
+    ),
+    (
+        "programs/gdal_raster_info",
+        "gdal-raster-info",
+        "Get information on a raster dataset",
+        [author_evenr],
+        1,
+    ),
+    (
+        "programs/gdal_raster_convert",
+        "gdal-raster-convert",
+        "Convert a raster dataset",
+        [author_evenr],
+        1,
+    ),
+    (
+        "programs/gdal_vector",
+        "gdal-vector",
+        "Entry point for vector commands",
+        [author_evenr],
+        1,
+    ),
+    (
+        "programs/gdal_vector_info",
+        "gdal-vector-info",
+        "Get information on a vector dataset",
+        [author_evenr],
+        1,
+    ),
+    # Traditional utilities
     (
         "programs/gdalinfo",
         "gdalinfo",
@@ -593,3 +645,24 @@
 nb_mime_priority_overrides = [
     ("spelling", "text/plain", 0),
 ]
+
+# -- copy data files -----------------------------------------------------
+
+data_dir = os.path.join(os.path.dirname(__file__), "..", "data")
+os.makedirs(data_dir, exist_ok=True)
+data_dir_with_stats = os.path.join(data_dir, "with_stats")
+os.makedirs(data_dir_with_stats, exist_ok=True)
+
+target_filename = os.path.join(data_dir, "utmsmall.tif")
+shutil.copy(
+    os.path.join(os.path.dirname(__file__), "../../autotest/gcore/data/utmsmall.tif"),
+    target_filename,
+)
+if os.path.exists(target_filename + ".aux.xml"):
+    os.unlink(target_filename + ".aux.xml")
+
+target_filename = os.path.join(data_dir_with_stats, "utmsmall.tif")
+shutil.copy(
+    os.path.join(os.path.dirname(__file__), "../../autotest/gcore/data/utmsmall.tif"),
+    target_filename,
+)

doc/source/programs/gdal.rst

@@ -0,0 +1,53 @@
+.. _gdal_program:
+
+================================================================================
+gdal
+================================================================================
+
+.. versionadded:: 3.11
+
+.. only:: html
+
+    Main "gdal" entry point.
+
+.. Index:: gdal
+
+Synopsis
+--------
+
+.. code-block::
+
+    Usage: gdal <COMMAND>
+    where <COMMAND> is one of:
+      - convert:  Convert a dataset (shortcut for 'gdal raster convert' or 'gdal vector convert').
+      - info:     Return information on a dataset (shortcut for 'gdal raster info' or 'gdal vector info').
+      - pipeline: Execute a pipeline (shortcut for 'gdal vector pipeline').
+      - raster:   Raster commands.
+      - vector:   Vector commands.
+
+    'gdal <FILENAME>' can also be used as a shortcut for 'gdal info <FILENAME>'.
+    And 'gdal read <FILENAME> ! ...' as a shortcut for 'gdal pipeline <FILENAME> ! ...'.
+
+Examples
+--------
+
+.. example::
+   :title: Getting information on the file :file:`utm.tif` (with JSON output)
+
+   .. code-block:: console
+
+       $ gdal info utm.tif
+
+.. example::
+   :title: Converting file :file:`utm.tif` to GeoPackage raster
+
+   .. code-block:: console
+
+       $ gdal convert utm.tif utm.gpkg
+
+.. example::
+   :title: Getting information on all available commands and subcommands as a JSON document.
+
+   .. code-block:: console
+
+       $ gdal --json-usage

doc/source/programs/gdal_info.rst

@@ -0,0 +1,54 @@
+.. _gdal_info_command:
+
+================================================================================
+"gdal info" command
+================================================================================
+
+.. versionadded:: 3.11
+
+.. only:: html
+
+    Get information on a dataset.
+
+.. Index:: gdal info
+
+Acts as a shortcut for :ref:`gdal_raster_info_subcommand` or
+:ref:`gdal_vector_info_subcommand` depending on the nature of the specified dataset.
+
+Synopsis
+--------
+
+.. code-block::
+
+    Usage: gdal info [OPTIONS] <INPUT>
+
+    Return information on a dataset (shortcut for 'gdal raster info' or 'gdal vector info').
+
+    Positional arguments:
+      -i, --input <INPUT>                                  Input raster, vector or multidimensional raster dataset [required]
+
+    Common Options:
+      -h, --help                                           Display help message and exit
+      --json-usage                                         Display usage as JSON document and exit
+
+    Options:
+      -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format. OUTPUT-FORMAT=json|text (default: json)
+
+    For all options, run 'gdal raster info --help' or 'gdal vector info --help'
+
+Examples
+--------
+
+.. example::
+   :title: Getting information on the file :file:`utm.tif` (with JSON output)
+
+   .. code-block:: console
+
+       $ gdal info utm.tif
+
+.. example::
+   :title: Getting information on the file :file:`poly.gpkg` (with text output), listing all features
+
+   .. code-block:: console
+
+       $ gdal info --format=text --features poly.gpkg

doc/source/programs/gdal_options/co.rst

@@ -0,0 +1,17 @@
+.. option:: --co <NAME>=<VALUE>
+
+    Many formats have one or more optional creation options that can be
+    used to control particulars about the file created. For instance,
+    the GeoTIFF driver supports creation options to control compression,
+    and whether the file should be tiled.
+
+    May be repeated.
+
+    The creation options available vary by format driver, and some
+    simple formats have no creation options at all. A list of options
+    supported for a format can be listed with the
+    :ref:`--formats <raster_common_options_formats>`
+    command line option but the documentation for the format is the
+    definitive source of information on driver creation options.
+    See :ref:`raster_drivers` format
+    specific documentation for legal creation options for each format.

doc/source/programs/gdal_options/if.rst

@@ -0,0 +1,10 @@
+.. option:: --if <format>
+
+    Format/driver name to be attempted to open the input file(s). It is generally
+    not necessary to specify it, but it can be used to skip automatic driver
+    detection, when it fails to select the appropriate driver.
+    This option can be repeated several times to specify several candidate drivers.
+    Note that it does not force those drivers to open the dataset. In particular,
+    some drivers have requirements on file extensions.
+
+    May be repeated.

doc/source/programs/gdal_options/of_raster_create_copy.rst

@@ -0,0 +1,5 @@
+
+.. option:: -f, --of, --format, --output-format <OUTPUT-FORMAT>
+
+    Which output raster format to use. Allowed values may be given by
+    ``gdal --formats | grep "\-raster\-" | grep "rw" | sort``

doc/source/programs/gdal_options/oo.rst

@@ -0,0 +1,5 @@
+.. option:: --oo <NAME>=<VALUE>
+
+    Dataset open option (format specific).
+
+    May be repeated.

doc/source/programs/gdal_options/overwrite.rst

@@ -0,0 +1,6 @@
+.. option:: --overwrite
+
+    Allow program to overwrite existing target file or dataset.
+    Otherwise, by default, :program:`gdal` errors out if the target file or
+    dataset already exists.
+

doc/source/programs/gdal_raster.rst

@@ -0,0 +1,46 @@
+.. _gdal_raster_command:
+
+================================================================================
+"gdal raster" command
+================================================================================
+
+.. versionadded:: 3.11
+
+.. only:: html
+
+    Entry point for raster commands
+
+.. Index:: gdal raster
+
+Synopsis
+--------
+
+.. code-block::
+
+    Usage: gdal raster <SUBCOMMAND>
+    where <SUBCOMMAND> is one of:
+      - convert: Convert a raster dataset.
+      - info:    Return information on a raster dataset.
+
+Available sub-commands
+----------------------
+
+- :ref:`gdal_raster_info_subcommand`
+- :ref:`gdal_raster_convert_subcommand`
+
+Examples
+--------
+
+.. example::
+   :title: Getting information on the file :file:`utm.tif` (with JSON output)
+
+   .. code-block:: console
+
+       $ gdal raster info utm.tif
+
+.. example::
+   :title: Converting file :file:`utm.tif` to GeoPackage raster
+
+   .. code-block:: console
+
+       $ gdal raster convert utm.tif utm.gpkg

doc/source/programs/gdal_raster_convert.rst

@@ -0,0 +1,90 @@
+.. _gdal_raster_convert_subcommand:
+
+================================================================================
+"gdal raster convert" sub-command
+================================================================================
+
+.. versionadded:: 3.11
+
+.. only:: html
+
+    Convert a raster dataset.
+
+.. Index:: gdal raster convert
+
+Synopsis
+--------
+
+.. code-block::
+
+    Usage: gdal raster convert [OPTIONS] <INPUT> <OUTPUT>
+
+    Convert a raster dataset.
+
+    Positional arguments:
+      -i, --input <INPUT>                                  Input raster dataset [required]
+      -o, --output <OUTPUT>                                Output raster dataset (created by algorithm) [required]
+
+    Common Options:
+      -h, --help                                           Display help message and exit
+      --json-usage                                         Display usage as JSON document and exit
+      --progress                                           Display progress bar
+
+    Options:
+      -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format
+      --co, --creation-option <KEY>=<VALUE>                Creation option [may be repeated]
+      --overwrite                                          Whether overwriting existing output is allowed
+                                                           Mutually exclusive with --append
+      --append                                             Append as a subdataset to existing output
+                                                           Mutually exclusive with --overwrite
+
+    Advanced Options:
+      --oo, --open-option <KEY=VALUE>                      Open options [may be repeated]
+      --if, --input-format <INPUT-FORMAT>                  Input formats [may be repeated]
+
+Description
+-----------
+
+:program:`gdal raster convert` can be used to convert raster data between
+different formats.
+
+The following options are available:
+
+Standard options
+++++++++++++++++
+
+.. include:: gdal_options/of_raster_create_copy.rst
+
+.. include:: gdal_options/co.rst
+
+.. include:: gdal_options/overwrite.rst
+
+.. option:: --append
+
+    Append input raster as a new subdataset to existing output file.
+    Only works with drivers that support adding subdatasets such as
+    :ref:`raster.gtiff` and :ref:`raster.gpkg`
+
+Advanced options
+++++++++++++++++
+
+.. include:: gdal_options/oo.rst
+
+.. include:: gdal_options/if.rst
+
+Examples
+--------
+
+.. example::
+   :title: Converting file :file:`utm.tif` to a cloud-optimized GeoTIFF using JPEG compression
+
+   .. code-block:: console
+
+       $ gdal raster convert --format=COG --co COMPRESS=JPEG utm.tif utm_cog.tif
+
+.. example::
+   :title: Converting file :file:`utm.tif` to GeoPackage raster
+
+   .. code-block:: console
+
+       $ gdal raster convert utm.tif utm.gpkg