search

OSGeo / gdal

GDAL is an open source MIT licensed translator library for raster and vector geospatial data formats.
https://gdal.org
Other
4.91k stars 2.55k forks source link

Doc: Make CLI examples referenceable #11271

Open dbaston opened 3 days ago

dbaston commented 3 days ago

What does this PR do?

Tests out a pattern for enabling cross-references to specific code snippets. This makes it easy to jump from the description of a CLI argument to an example that uses it.

Sphinx allows a code block to have a name attribute, but to enable cross-referencing it must also have a caption. So I took the description of each snippet (previously written in plain text) and moved it into the caption. The default style for a caption looks a bit awkward:

image

so this PR overrides the CSS so that the "caption" is more of a title:

image

If the pattern looks OK, it can be applied to documentation for the other CLI tools.

rouault commented 3 days ago

LGTM. Maybe describe that in https://gdal.org/en/latest/development/dev_documentation.html#sphinx-rst-style-guide ?

dbaston commented 2 days ago

Going to spend a bit more time on this. It doesn't work well for multi-command examples. Maybe a custom directive is the way to go, if it can be done without too much code.