diff --git a/.github/workflows/doc_checks.yml b/.github/workflows/doc_checks.yml index 26502afd0062..545cb4eb5375 100644 --- a/.github/workflows/doc_checks.yml +++ b/.github/workflows/doc_checks.yml @@ -39,7 +39,7 @@ jobs: cmake .. \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=/usr \ - -DBUILD_APPS=OFF \ + -DBUILD_APPS=ON \ -DBUILD_TESTING=OFF \ -DGDAL_BUILD_OPTIONAL_DRIVERS=OFF \ -DOGR_BUILD_OPTIONAL_DRIVERS=OFF diff --git a/doc/requirements.txt b/doc/requirements.txt index 8e566338af66..da22d12e3326 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,14 +1,16 @@ # This file may be used to create an environment using: # $ pip install --upgrade -r +breathe fsspec numpy sphinx -breathe sphinx_bootstrap_theme -sphinxcontrib-bibtex -sphinx_rtd_theme -recommonmark sphinx-markdown-tables -sphinxcontrib-spelling +sphinx_rtd_theme +sphinxcontrib-bibtex sphinxcontrib-jquery +# We use a slightly forked version +# sphinxcontrib-programoutput +sphinxcontrib-spelling myst_nb +recommonmark diff --git a/doc/rtd/pre_build.sh b/doc/rtd/pre_build.sh index 56d8d8060346..3faeba2ffb56 100755 --- a/doc/rtd/pre_build.sh +++ b/doc/rtd/pre_build.sh @@ -13,7 +13,7 @@ cmake \ -DGDAL_PYTHON_INSTALL_PREFIX=${PREFIX} \ -DGDAL_BUILD_OPTIONAL_DRIVERS=OFF \ -DOGR_BUILD_OPTIONAL_DRIVERS=OFF \ - -DBUILD_APPS=OFF \ + -DBUILD_APPS=ON \ -DBUILD_PYTHON_BINDINGS=ON \ -DBUILD_JAVA_BINDINGS=ON \ -DBUILD_TESTING=OFF \ diff --git a/doc/source/_extensions/sphinxcontrib_programoutput_gdal.py b/doc/source/_extensions/sphinxcontrib_programoutput_gdal.py index deafb22acbde..66db1be0a7d3 100644 --- a/doc/source/_extensions/sphinxcontrib_programoutput_gdal.py +++ b/doc/source/_extensions/sphinxcontrib_programoutput_gdal.py @@ -1,3 +1,6 @@ +# Slightly customized version with a new 'language' option, submitted as +# https://github.com/OpenNTI/sphinxcontrib-programoutput/pull/62 + # -*- coding: utf-8 -*- # Copyright (c) 2010, 2011, 2012, Sebastian Wiesner # All rights reserved. @@ -92,7 +95,8 @@ class ProgramOutputDirective(rst.Directive): option_spec = dict(shell=flag, prompt=flag, nostderr=flag, ellipsis=_slice, extraargs=unchanged, returncode=nonnegative_int, cwd=unchanged, - caption=unchanged, name=unchanged) + caption=unchanged, name=unchanged, + language=unchanged) def run(self): env = self.state.document.settings.env @@ -112,6 +116,7 @@ def run(self): node['working_directory'] = cwd node['use_shell'] = 'shell' in self.options node['returncode'] = self.options.get('returncode', 0) + node['language'] = self.options.get('language', 'text') if 'ellipsis' in self.options: node['strip_lines'] = self.options['ellipsis'] if 'caption' in self.options: @@ -312,7 +317,7 @@ def run_programs(app, doctree): ) new_node = node_class(output, output) - new_node['language'] = 'text' + new_node['language'] = node['language'] node.replace_self(new_node) diff --git a/doc/source/conf.py b/doc/source/conf.py index 44dc7ae0f5d0..f3e323d38f13 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -71,6 +71,7 @@ "source_file", "sphinx.ext.napoleon", "sphinxcontrib.jquery", + "sphinxcontrib_programoutput_gdal", "sphinxcontrib.spelling", "myst_nb", ] diff --git a/doc/source/programs/gdalinfo.rst b/doc/source/programs/gdalinfo.rst index 01ef40ad0d97..66b7a6b6106e 100644 --- a/doc/source/programs/gdalinfo.rst +++ b/doc/source/programs/gdalinfo.rst @@ -184,286 +184,11 @@ This utility is also callable from C with :cpp:func:`GDALInfo`. Example ------- -.. code-block:: - - gdalinfo ~/openev/utm.tif - 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 +.. command-output:: gdalinfo ../../autotest/gcore/data/utmsmall.tif For corner coordinates formatted as decimal degree instead of the above degree, minute, second, inspect the ``wgs84Extent`` member of gdalinfo -json: -Example of JSON output with ``gdalinfo -json byte.tif`` - -.. code-block:: json - - { - "description":"byte.tif", - "driverShortName":"GTiff", - "driverLongName":"GeoTIFF", - "files":[ - "byte.tif" - ], - "size":[ - 20, - 20 - ], - "coordinateSystem":{ - "wkt":"PROJCRS[\"NAD27 / UTM zone 11N\",\n BASEGEOGCRS[\"NAD27\",\n DATUM[\"North American Datum 1927\",\n ELLIPSOID[\"Clarke 1866\",6378206.4,294.978698213898,\n LENGTHUNIT[\"metre\",1]]],\n PRIMEM[\"Greenwich\",0,\n ANGLEUNIT[\"degree\",0.0174532925199433]],\n ID[\"EPSG\",4267]],\n CONVERSION[\"UTM zone 11N\",\n METHOD[\"Transverse Mercator\",\n ID[\"EPSG\",9807]],\n PARAMETER[\"Latitude of natural origin\",0,\n ANGLEUNIT[\"degree\",0.0174532925199433],\n ID[\"EPSG\",8801]],\n PARAMETER[\"Longitude of natural origin\",-117,\n ANGLEUNIT[\"degree\",0.0174532925199433],\n ID[\"EPSG\",8802]],\n PARAMETER[\"Scale factor at natural origin\",0.9996,\n SCALEUNIT[\"unity\",1],\n ID[\"EPSG\",8805]],\n PARAMETER[\"False easting\",500000,\n LENGTHUNIT[\"metre\",1],\n ID[\"EPSG\",8806]],\n PARAMETER[\"False northing\",0,\n LENGTHUNIT[\"metre\",1],\n ID[\"EPSG\",8807]]],\n CS[Cartesian,2],\n AXIS[\"(E)\",east,\n ORDER[1],\n LENGTHUNIT[\"metre\",1]],\n AXIS[\"(N)\",north,\n ORDER[2],\n LENGTHUNIT[\"metre\",1]],\n USAGE[\n SCOPE[\"Engineering survey, topographic mapping.\"],\n AREA[\"North America - between 120°W and 114°W - onshore. Canada - Alberta; British Columbia; Northwest Territories; Nunavut. Mexico. United States (USA) - California; Idaho; Nevada; Oregon; Washington.\"],\n BBOX[26.93,-120,78.13,-114]],\n ID[\"EPSG\",26711]]", - "dataAxisToSRSAxisMapping":[ - 1, - 2 - ] - }, - "geoTransform":[ - 440720.0, - 60.0, - 0.0, - 3751320.0, - 0.0, - -60.0 - ], - "metadata":{ - "":{ - "AREA_OR_POINT":"Area" - }, - "IMAGE_STRUCTURE":{ - "INTERLEAVE":"BAND" - } - }, - "cornerCoordinates":{ - "upperLeft":[ - 440720.0, - 3751320.0 - ], - "lowerLeft":[ - 440720.0, - 3750120.0 - ], - "lowerRight":[ - 441920.0, - 3750120.0 - ], - "upperRight":[ - 441920.0, - 3751320.0 - ], - "center":[ - 441320.0, - 3750720.0 - ] - }, - "wgs84Extent":{ - "type":"Polygon", - "coordinates":[ - [ - [ - -117.6420428, - 33.9023684 - ], - [ - -117.6419617, - 33.8915461 - ], - [ - -117.6289846, - 33.8916131 - ], - [ - -117.629064, - 33.9024353 - ], - [ - -117.6420428, - 33.9023684 - ] - ] - ] - }, - "bands":[ - { - "band":1, - "block":[ - 20, - 20 - ], - "type":"Byte", - "colorInterpretation":"Gray", - "metadata":{ - } - } - ], - "stac":{ - "proj:shape":[ - 20, - 20 - ], - "proj:wkt2":"PROJCRS[\"NAD27 / UTM zone 11N\",\n BASEGEOGCRS[\"NAD27\",\n DATUM[\"North American Datum 1927\",\n ELLIPSOID[\"Clarke 1866\",6378206.4,294.978698213898,\n LENGTHUNIT[\"metre\",1]]],\n PRIMEM[\"Greenwich\",0,\n ANGLEUNIT[\"degree\",0.0174532925199433]],\n ID[\"EPSG\",4267]],\n CONVERSION[\"UTM zone 11N\",\n METHOD[\"Transverse Mercator\",\n ID[\"EPSG\",9807]],\n PARAMETER[\"Latitude of natural origin\",0,\n ANGLEUNIT[\"degree\",0.0174532925199433],\n ID[\"EPSG\",8801]],\n PARAMETER[\"Longitude of natural origin\",-117,\n ANGLEUNIT[\"degree\",0.0174532925199433],\n ID[\"EPSG\",8802]],\n PARAMETER[\"Scale factor at natural origin\",0.9996,\n SCALEUNIT[\"unity\",1],\n ID[\"EPSG\",8805]],\n PARAMETER[\"False easting\",500000,\n LENGTHUNIT[\"metre\",1],\n ID[\"EPSG\",8806]],\n PARAMETER[\"False northing\",0,\n LENGTHUNIT[\"metre\",1],\n ID[\"EPSG\",8807]]],\n CS[Cartesian,2],\n AXIS[\"(E)\",east,\n ORDER[1],\n LENGTHUNIT[\"metre\",1]],\n AXIS[\"(N)\",north,\n ORDER[2],\n LENGTHUNIT[\"metre\",1]],\n USAGE[\n SCOPE[\"Engineering survey, topographic mapping.\"],\n AREA[\"North America - between 120°W and 114°W - onshore. Canada - Alberta; British Columbia; Northwest Territories; Nunavut. Mexico. United States (USA) - California; Idaho; Nevada; Oregon; Washington.\"],\n BBOX[26.93,-120,78.13,-114]],\n ID[\"EPSG\",26711]]", - "proj:epsg":26711, - "proj:projjson":{ - "$schema":"https://proj.org/schemas/v0.6/projjson.schema.json", - "type":"ProjectedCRS", - "name":"NAD27 / UTM zone 11N", - "base_crs":{ - "name":"NAD27", - "datum":{ - "type":"GeodeticReferenceFrame", - "name":"North American Datum 1927", - "ellipsoid":{ - "name":"Clarke 1866", - "semi_major_axis":6378206.4, - "semi_minor_axis":6356583.8 - } - }, - "coordinate_system":{ - "subtype":"ellipsoidal", - "axis":[ - { - "name":"Geodetic latitude", - "abbreviation":"Lat", - "direction":"north", - "unit":"degree" - }, - { - "name":"Geodetic longitude", - "abbreviation":"Lon", - "direction":"east", - "unit":"degree" - } - ] - }, - "id":{ - "authority":"EPSG", - "code":4267 - } - }, - "conversion":{ - "name":"UTM zone 11N", - "method":{ - "name":"Transverse Mercator", - "id":{ - "authority":"EPSG", - "code":9807 - } - }, - "parameters":[ - { - "name":"Latitude of natural origin", - "value":0, - "unit":"degree", - "id":{ - "authority":"EPSG", - "code":8801 - } - }, - { - "name":"Longitude of natural origin", - "value":-117, - "unit":"degree", - "id":{ - "authority":"EPSG", - "code":8802 - } - }, - { - "name":"Scale factor at natural origin", - "value":0.9996, - "unit":"unity", - "id":{ - "authority":"EPSG", - "code":8805 - } - }, - { - "name":"False easting", - "value":500000, - "unit":"metre", - "id":{ - "authority":"EPSG", - "code":8806 - } - }, - { - "name":"False northing", - "value":0, - "unit":"metre", - "id":{ - "authority":"EPSG", - "code":8807 - } - } - ] - }, - "coordinate_system":{ - "subtype":"Cartesian", - "axis":[ - { - "name":"Easting", - "abbreviation":"E", - "direction":"east", - "unit":"metre" - }, - { - "name":"Northing", - "abbreviation":"N", - "direction":"north", - "unit":"metre" - } - ] - }, - "scope":"Engineering survey, topographic mapping.", - "area":"North America - between 120°W and 114°W - onshore. Canada - Alberta; British Columbia; Northwest Territories; Nunavut. Mexico. United States (USA) - California; Idaho; Nevada; Oregon; Washington.", - "bbox":{ - "south_latitude":26.93, - "west_longitude":-120, - "north_latitude":78.13, - "east_longitude":-114 - }, - "id":{ - "authority":"EPSG", - "code":26711 - } - }, - "proj:transform":[ - 440720.0, - 60.0, - 0.0, - 3751320.0, - 0.0, - -60.0 - ], - "raster:bands":[ - { - "data_type":"uint8" - } - ], - "eo:bands":[ - { - "name":"b1", - "description":"Gray" - } - ] - } - } +Example of JSON output with `gdalinfo -json ../../autotest/gcore/data/utmsmall.tif`: + +.. program-output:: gdalinfo -json ../../autotest/gcore/data/utmsmall.tif + :language: json