OSGeo / gdal

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

Doc: use myst-nb with ipython3 and shell execution for gdalinfo outputs #11298

Closed rouault closed 2 days ago

rouault commented 2 days ago

I tried to use the "bash" jupyter kernel, but the output is not satisfactory as there is a padding line between each output line. And if using the merge_streams: True option as done with the "python" kernel, which fixes that issue, in bash mode, leading spaces are also removed, breaking the indentation. The annoying thing with the solution in this PR is that if we don't add :tags: [remove-input] in the code-cell, the leading "!" character will appear in the output HTML/PDF, which isn't expected in that context. Thus we have to hide the cell input, and use standard markdown to make it appear.

dbaston commented 2 days ago

This pattern seems like it would make the docs more difficult to maintain. I think we should really try to avoid a big mixture of rst and markdown. If we want to automatically run bash commands from the program docs (the number of cases where this would be useful seems small) then we might try https://sphinxcontrib-programoutput.readthedocs.io/en/latest/

rouault commented 2 days ago

This pattern seems like it would make the docs more difficult to maintain

agreed. Following your suggestion, closing this PR as superseded per https://github.com/OSGeo/gdal/pull/11301