Skip to content

Conversation

@geographika
Copy link
Collaborator

This PR contains a first draft of a GDAL command-line cookbook (see #12089). It will need many more examples before getting enough content to be considered for merging, this initial commit is to get agreement on an approach.

The approach aims to:

  • avoid repeating examples, by linking to specific examples if appropriate
  • link to the examples section of the appropriate tool for more generic questions
  • add examples directly to the page if they are not covered elsewhere
  • uses traditional and new CLI examples, and PowerShell for Windows users where the example syntax is very different or confusing
  • does not cover Python examples - I think this may overwhelm the page, and may be better on a separate page

I went through a few iterations of the page structure (Q&A, bulleted lists), but the use of titles provides a nice page table of contents and linking.

I tried to update the https://github.com/OSGeo/gdal/blob/master/doc/source/_extensions/cli_example.py to allow for global example references, but there were issues with parallel Sphinx builds and having to process each file twice so I stopped. It may just be easier to add :ref:s directly above linked examples.

@dbaston @rouault - let me know your thoughts on the approach and structure.

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

@dbaston dbaston left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • I would put all new examples on the pages for the CLI tools and have the cookbook link to them.
  • I can handle updating .. example:: so we don't have to maintain separate reference links.
  • I don't think we necessarily need to add new examples for ogr2ogr, ogrinfo etc.

.. code-tab:: bash

export OGR_SQLITE_ALLOW_EXTERNAL_ACCESS="YES"
gdal vector sql points.gpkg \
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Off topic for this PR, but we should probably improve gdal raster pixel-info to have a less convoluted way of doing this.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was quite please with myself to get that example working 😄

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but we should probably improve gdal raster pixel-info to have a less convoluted way of doing this.

I'll tackle that

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