Skip to content

Doc: Add .. program:: directives to new CLI tool help pages#14686

Merged
rouault merged 11 commits into
OSGeo:masterfrom
geographika:program-directives
May 29, 2026
Merged

Doc: Add .. program:: directives to new CLI tool help pages#14686
rouault merged 11 commits into
OSGeo:masterfrom
geographika:program-directives

Conversation

@geographika

@geographika geographika commented May 29, 2026

Copy link
Copy Markdown
Collaborator

This pull request adds .. program:: directives (see docs) as discussed in #14670.

This has the following advantages:

  1. Previously, uses of :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.
  2. We can now link directly to an option from another page (see examples at b3059d1) using the syntax :option:`--overwrite <gdal_vector_buffer --overwrite> .
  3. Adding the .. 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:--resolution and `:option:`--size because these options are not available in gdal raster update (they are available in gdal raster project)
  • added doc/source/programs/gdal_options/input_layer_no_active_layer.rst for vector programs that use --input-layer but do not provide an --active-layer option, which was previously referenced in gdal_options/input_layer.rst
  • added the missing --geometry-field option to gdal vector create
  • removed the link to --add-alpha from gdal raster stack because this option is not available
  • added the missing short-form option -r, which was linked to from gdal raster overview refresh and gdal raster overview add

I 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.

@rouault rouault merged commit 512cda7 into OSGeo:master May 29, 2026
2 checks passed
@geographika geographika added documentation Issues and contributions to the documentation content funded through GSP Work funded through the GDAL Sponsorship Program labels May 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Issues and contributions to the documentation content funded through GSP Work funded through the GDAL Sponsorship Program

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants