Skip to content

GDAL cli cookbook#14032

Open
geographika wants to merge 14 commits intoOSGeo:masterfrom
geographika:cookboox
Open

GDAL cli cookbook#14032
geographika wants to merge 14 commits intoOSGeo:masterfrom
geographika:cookboox

Conversation

@geographika
Copy link
Collaborator

@geographika geographika commented Feb 27, 2026

A new draft of the cookbook, replacing #13810. This approach avoids adding examples directly to the page, but instead links to examples on the relevant command pages using the custom Sphinx directive updated in #14007.

Other changes:

  • added several new examples
  • added a note about use of the jq tool for parsing JSON output (and updated URL)
  • updated spelling list as example titles appear on other pages

I ran through a few different design choices for the layout, before setting on this approach inspired by the Sphinx FAQs.

Other options I tried included:

:Q: How do I buffer geometries?
:A: :example:`gdal-vector-buffer-1km`

and:

.. rubric:: Frequently Asked Questions

How do I get the GDAL version?
    :example:`gdal-version`.

@dbaston I modified the Examples, directive to show the :title: rather than the autogenerated page and example number. Let me know your thoughts on this.

Automated titles:

example-automated

Updated to use example titles:

examples-titles

Other modifications to the extension were to handle example titles that included formatting e.g. literals. If reverting to the original automated :ref: titles then the extension needs to use .astext() or the doc pages end up formatted as <literal>gdal vector buffer</literal>.

example_doc_title = str(env.titles[example.docname].children[0].astext())

@geographika geographika added funded through GSP Work funded through the GDAL Sponsorship Program documentation Issues and contributions to the documentation content labels Feb 27, 2026
@rouault
Copy link
Member

rouault commented Mar 12, 2026

@geographika is the Draft status still valid or can that be merged?

@geographika geographika marked this pull request as ready for review March 13, 2026 06:57
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.

3 participants