Skip to content

Commit

Permalink
Doc: use sphinxcontrib_programoutput_gdal for gdalinfo doc
Browse files Browse the repository at this point in the history 
We use a slightly enhanced version of https://github.com/OpenNTI/sphinxcontrib-programoutput
with a new 'language' option. Enhancement proposed at
OpenNTI/sphinxcontrib-programoutput#62
  • Loading branch information
@rouault
rouault committed Nov 19, 2024
1 parent 96ada76 commit 94aff32
Show file tree
Hide file tree
Showing 5 changed files with 21 additions and 288 deletions.
12 changes: 7 additions & 5 deletions doc/requirements.txt
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,16 @@
# This file may be used to create an environment using:
# $ pip install --upgrade -r <this file>
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
2 changes: 1 addition & 1 deletion doc/rtd/pre_build.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down
9 changes: 7 additions & 2 deletions doc/source/_extensions/sphinxcontrib_programoutput_gdal.py
View file
Original file line number Diff line number Diff line change
@@ -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 <lunaryorn@gmail.com>
# All rights reserved.
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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)


Expand Down
1 change: 1 addition & 0 deletions doc/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,7 @@
"source_file",
"sphinx.ext.napoleon",
"sphinxcontrib.jquery",
"sphinxcontrib_programoutput_gdal",
"sphinxcontrib.spelling",
"myst_nb",
]
Expand Down
285 changes: 5 additions & 280 deletions doc/source/programs/gdalinfo.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

0 comments on commit 94aff32

Please sign in to comment.