Doc: Add .. program:: directives to new CLI tool help pages#14686
Merged
Conversation
…resolution or --size options
rouault
approved these changes
May 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request adds
.. program::directives (see docs) as discussed in #14670.This has the following advantages:
:option: ...could link to a random page (specifically, the first page processed by Sphinx) rather than to the correct option on the program help page (see the example in Doc::option:directives link to incorrect pages #14670 although this issue was widespread). These links are now fixed.:option:`--overwrite <gdal_vector_buffer --overwrite>... program::directive highlights invalid options and broken option links on program pages. These issues have been addressed and are discussed below. Sphinx will also catch any new errors introduced on these pages.Some program help pages used RST include files that linked to options not available for that program.
doc/source/programs/gdal_options/warp_resampling.rst:removed the note linking to
:option:--resolutionand `:option:`--sizebecause these options are not available ingdal raster update(they are available ingdal raster project)doc/source/programs/gdal_options/input_layer_no_active_layer.rstfor vector programs that use--input-layerbut do not provide an--active-layeroption, which was previously referenced ingdal_options/input_layer.rst--geometry-fieldoption togdal vector create--add-alphafromgdal raster stackbecause this option is not available-r, which was linked to fromgdal raster overview refreshandgdal raster overview addI have not yet applied the
.. program::directive to the "traditional" pages. Most of these already include it, but I can review and add any missing directives in a separate PR.