Merge pull request OSGeo#11271 from dbaston/doc-gdal-calc

Doc: Make CLI examples referenceable

doc/source/_extensions/cli_example.py

@@ -0,0 +1,137 @@
+from docutils import nodes
+from sphinx.addnodes import pending_xref
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective, SphinxRole
+
+
+class ExampleRole(SphinxRole):
+    def run(self):
+        return [
+            pending_xref(
+                "",
+                nodes.Text("placeholder"),
+                reftype="example",
+                refdomain="std",
+                reftarget=self.text,
+            )
+        ], []
+
+    def run_bad(self):
+        # ref_node = pending_xref(reftarget=self.text)
+
+        if hasattr(self.env, "gdal_examples"):
+            examples = self.env.gdal_examples.get(self.env.docname, {})
+        else:
+            examples = {}
+
+        ref_node = nodes.reference("", "", refid=self.text)
+        ref_node.append(nodes.Text(f"Example {examples.get(self.text)}"))
+
+        return [ref_node], []
+
+
+class ExampleDirective(SphinxDirective):
+
+    required_arguments = 0
+    has_content = True
+
+    option_spec = {
+        "title": str,
+        "id": str,
+    }
+
+    def run(self):
+        docname = self.env.docname
+
+        if not hasattr(self.env, "gdal_examples"):
+            self.env.gdal_examples = {}
+
+        if docname not in self.env.gdal_examples:
+            self.env.gdal_examples[docname] = {}
+
+        examples = self.env.gdal_examples[docname]
+
+        example_num = len(examples) + 1
+
+        title_content = self.options.get("title", None)
+        if title_content:
+            title_content = f"Example {example_num}: {title_content}"
+        else:
+            title_content = f"Example {example_num}"
+
+        id = self.options.get("id", f"{docname}-{example_num}")
+        examples[id] = example_num
+
+        retnodes = []
+        section = nodes.section(ids=[id])
+        section.document = self.state.document
+
+        title = nodes.title()
+        title += self.parse_inline(title_content)[0]
+        section.append(title)
+        self.state.nested_parse(self.content, self.content_offset, section)
+
+        retnodes.append(section)
+
+        return retnodes
+
+
+def link_example_refs(app, env, node, contnode):
+    if node["reftype"] != "example":
+        return
+
+    example_name = node["reftarget"]
+
+    if hasattr(env, "gdal_examples"):
+        examples = env.gdal_examples.get(env.docname, {})
+    else:
+        examples = {}
+
+    example_num = examples.get(example_name, None)
+
+    if not example_num:
+        logger = logging.getLogger(__name__)
+
+        logger.warning(
+            f"Can't find example {example_name}",
+            location=node,
+        )
+
+        return contnode
+
+    ref_node = nodes.reference("", "", refid=node["reftarget"], internal=True)
+    ref_node.append(nodes.Text(f'Example {examples.get(node["reftarget"])}'))
+
+    return ref_node
+
+
+def purge_example_defs(app, env, docname):
+    if not hasattr(env, "gdal_examples"):
+        return
+
+    if docname in env.gdal_examples:
+        del env.gdal_examples[docname]
+
+
+def merge_example_defs(app, env, docnames, other):
+    if not hasattr(env, "gdal_examples"):
+        env.gdal_examples = {}
+
+    if hasattr(other, "gdal_examples"):
+        env.gdal_examples.update(other.gdal_examples)
+
+
+def setup(app):
+    app.add_directive("example", ExampleDirective)
+    app.add_role("example", ExampleRole())
+
+    app.connect("env-purge-doc", purge_example_defs)
+    app.connect("env-merge-info", merge_example_defs)
+
+    app.connect("missing-reference", link_example_refs)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

doc/source/_extensions/configoptions.py

@@ -133,7 +133,7 @@ def render(self, app):
                 logger = logging.getLogger(__name__)
                 logger.warning(
                     f"Option {self.option_name} :since: should be a sequence of integers and periods (got {self.since_ver})",
-                    location=self.env.docname,
+                    location=app.env.docname,
                 )
 
         if caveats:

doc/source/conf.py

@@ -68,6 +68,7 @@
     "breathe",
     "configoptions",
     "driverproperties",
+    "cli_example",
     "source_file",
     "sphinx.ext.napoleon",
     "sphinxcontrib.jquery",

doc/source/development/dev_documentation.rst

@@ -341,6 +341,46 @@ To reference a method or function::
   :cpp:func:`MyClass::MyMethod`
   :cpp:func:`MyFunction`
 
+
+Command-line program usage
+--------------------------
+
+To document a command-line tool, use the ``example`` directive.
+An example may have a title as well as an id that can be used to generate
+a cross-reference from the same document.
+
+.. code-block:: rst
+
+    .. example::
+       :title: Listing files
+       :id: basic-ls
+
+       Files can be listed as follows:
+
+       .. code-block:: bash
+
+          ls
+
+    The ``ls`` command is demonstrated in :example:`basic-ls`.
+
+If output of the command is to be included in the listing, the code language
+should be set to ``console``:
+
+.. code-block:: rst
+
+   .. code-block:: console
+
+   $ gdalinfo --version
+   GDAL 3.4.1, released 2021/12/27
+
+To run the command and collect its output when the documentation is built, use the ``command-output`` directive.
+
+.. code-block:: rst
+
+   .. command-output:: ogrinfo poly.shp
+      :cwd: ../../../autotest/ogr/data
+
+
 .. _config_option_syntax:
 
 Define and reference configuration options

doc/source/programs/gdal2tiles.rst

@@ -298,22 +298,25 @@ The following configuration options are available to further customize the JPEG
 Examples
 --------
 
-Basic example:
+.. example::
+   :title: Basic example
 
-.. code-block::
+   .. code-block:: bash
 
-  gdal2tiles --zoom=2-5 input.tif output_folder
+      gdal2tiles --zoom=2-5 input.tif output_folder
 
 
-MapML generation:
+.. example::
+   :title: MapML generation
 
-.. code-block::
+   .. code-block:: bash
 
-  gdal2tiles --zoom=16-18 -w mapml -p APSTILE --url "https://example.com" input.tif output_folder
+      gdal2tiles --zoom=16-18 -w mapml -p APSTILE --url "https://example.com" input.tif output_folder
 
 
-MPI example:
+.. example::
+   :title: MPI example
 
-.. code-block::
+    .. code-block:: bash
 
-  mpiexec -n $NB_PROCESSES gdal2tiles --mpi --config GDAL_CACHEMAX 500 --zoom=2-5 input.tif output_folder
+       mpiexec -n $NB_PROCESSES gdal2tiles --mpi --config GDAL_CACHEMAX 500 --zoom=2-5 input.tif output_folder

doc/source/programs/gdal2xyz.rst

@@ -99,15 +99,17 @@ The :program:`gdal2xyz` utility can be used to translate a raster file into xyz
 Examples
 --------
 
-::
+.. example::
 
-    gdal2xyz -b 1 -b 2 -dstnodata 0 input.tif output.txt
+   .. code-block:: bash
 
+       gdal2xyz -b 1 -b 2 -dstnodata 0 input.tif output.txt
 
-To create a text file in `xyz` format from the input file `input.tif`.
-The first columns, x and y, are the coordinates of the centers of each cell.
-The remaining columns represent the first and second bands.
-We also replace the dataset nodata values with zeros.
+
+   To create a text file in `xyz` format from the input file `input.tif`.
+   The first columns, x and y, are the coordinates of the centers of each cell.
+   The remaining columns represent the first and second bands.
+   We also replace the dataset nodata values with zeros.
 
 
 Caveats