[pull] master from OSGeo:master

.github/workflows/code_checks.yml

@@ -164,18 +164,6 @@ jobs:
       - uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
       - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
 
-  doxygen:
-    runs-on: ubuntu-latest
-    container: ghcr.io/osgeo/proj-docs
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Run doxygen
-        run: |
-            cd doc
-            make doxygen_check_warnings
-
   other_checks:
     runs-on: ubuntu-24.04
     steps:

.github/workflows/doc_checks.yml

@@ -21,52 +21,44 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: true
-    container: ghcr.io/osgeo/proj-docs
+    container: ubuntu:24.04
 
     steps:
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
     - name: Setup environment
       shell: bash -l {0}
+      env:
+        DEBIAN_FRONTEND: noninteractive
       run: |
           apt update
-          apt install -y libproj-dev swig
-          PYTHON_CMD=python3 && $PYTHON_CMD -m pip install -r doc/requirements.txt
-          PYTHON_CMD=python3 && $PYTHON_CMD -m pip install numpy setuptools
-          pushd .
+          apt install -y g++ cmake doxygen enchant-2 python3 python3-dev python3-pip python3-venv libproj-dev swig
+          python3 -m venv create doc_env
+          . doc_env/bin/activate
+          python3 -m pip install -r doc/requirements.txt
+          echo PATH=$PATH >> $GITHUB_ENV
+
+    - name: Build GDAL
+      shell: bash -l {0}
+      run: |
           mkdir build
           cd build
-          export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
           cmake .. \
-            -DCMAKE_BUILD_TYPE=Release \
-            -DCMAKE_INSTALL_PREFIX=/usr \
+            -DCMAKE_BUILD_TYPE=Debug \
             -DBUILD_APPS=ON \
-            -DBUILD_TESTING=OFF \
+            -DBUILD_DOCS=ON \
+            -DBUILD_TESTING=ON \
             -DGDAL_BUILD_OPTIONAL_DRIVERS=OFF \
             -DOGR_BUILD_OPTIONAL_DRIVERS=OFF
           cmake --build . -j$(nproc)
-          cmake --install .
-          # With the new ghcr.io/osgeo/proj-docs image based on Ubuntu 24.04
-          # a venv is activated. The above does not install the
-          # Python bindings into it (and the ones in the system are not found
-          # without overriding PYTHONPATH), so do it through pip install
-          cd swig/python
-          python3 setup.py sdist
-          cp dist/* /tmp/gdal.tar.gz
-          PYTHON_CMD=python3 && $PYTHON_CMD -m pip install /tmp/gdal.tar.gz
-          ldconfig
-          popd
-
-    - name: Update components
-      shell: bash -l {0}
-      run: |
-          PYTHON_CMD=python3 && $PYTHON_CMD -m pip install -U "sphinx-rtd-theme>=3.0.0" "sphinxcontrib-spelling>=8.0.0"
 
     - name: Print versions
       shell: bash -l {0}
       run: |
+          which python3
           python3 --version
           sphinx-build --version
-          PYTHON_CMD=python3 && $PYTHON_CMD -m pip list --not-required --format=columns
+          python3 -m pip list --not-required --format=columns
+
     - name: Lint .rst files
       shell: bash -l {0}
       run: |
@@ -79,11 +71,11 @@ jobs:
     - name: Doxygen
       shell: bash -l {0}
       run: |
-        mkdir -p doc/build
-        doxygen Doxyfile
+        cmake --build . --target doxygen_xml
+      working-directory: build
     - name: Spelling
       shell: bash -l {0}
       run: |
-        sed -i '/html_extra_path/d' source/conf.py # avoid WARNING: html_extra_path entry '../build/html_extra' is placed inside outdir
-        make spelling
-      working-directory: ./doc
+        python3 -c 'from osgeo import gdal'
+        ctest -V -R spelling --output-on-failure
+      working-directory: build

.readthedocs.yaml

@@ -15,7 +15,6 @@ build:
       - (git --no-pager log --pretty="tformat:%s -- %b" -1 | paste -s -d " " | grep -viqP "skip ci|ci skip") || exit 183
     pre_build:
       - ./doc/rtd/pre_build.sh
-      - cd doc && make doxygen
 
   apt_packages:
     - ant

HOWTO-RELEASE

@@ -90,8 +90,12 @@ Process :
 
    If make is not GNU make, e.g., export MAKE=gmake
 
+   ant used for building Javadocs
+
    doxygen
 
+   jdk used for building Javadocs
+
    python available as "python", or e.g. export PYTHON=python3.9
 
    python3 available as "python3" in path (export PYTHON=python3.9
@@ -105,7 +109,7 @@ Process :
 
    md5sum (GNU version) in path (not a POSIX requirement)
 
-12.1) Create the source distributions using the mkgdaldist.sh script.
+12.1) Create the source distributions and documentation snapshot using the mkgdaldist.sh script.
    The argument should be the version number (i.e. 1.4.2). As our process involves
    doing betas or RCs, use the -rc option so that the filenames include this
    information (after promotion to official release, filename renaming will have
@@ -126,17 +130,7 @@ Process :
    a previous release (diff -Nur gdal-3.0.1 gdal-3.0.2).
    This is more easily doable for a bugfix release.
 
-12.2) Create a snapshot of the documentation (only for feature releases)
-
-    1. Refresh
-       https://download.osgeo.org/gdal/for_doc/javadoc.zip
-       by building the Java bindings, with -DGDAL_JAVA_GENERATE_JAVADOC=ON.
-       javadoc.zip is in the swig/java subdirectory of the build directory.
-    2. cd doc
-    3. ./build_doc_snapshot 310
-       This generates gdal310doc.zip
-
-12.3) Publish the resulting files on download.osgeo.org,
+12.2) Publish the resulting files on download.osgeo.org,
     in /osgeo/download/gdal/X.Y.Z (where X.Y.Z is the version number)
 
     with ~/.ssh/config containing:

alg/viewshed/viewshed_executor.cpp

@@ -93,7 +93,7 @@ double doMax(int nXOffset, int nYOffset, double dfThisPrev, double dfLast,
 
 }  // unnamed namespace
 
-/// Constructor -- the viewshed algorithm executor
+/// Constructor - the viewshed algorithm executor
 /// @param srcBand  Source raster band
 /// @param dstBand  Destination raster band
 /// @param nX  X position of observer

apps/gdalalg_raster_pipeline.cpp

@@ -178,7 +178,14 @@ bool GDALRasterPipelineAlgorithm::ParseCommandLineArguments(
 {
     if (args.size() == 1 && (args[0] == "-h" || args[0] == "--help" ||
                              args[0] == "help" || args[0] == "--json-usage"))
+    {
         return GDALAlgorithm::ParseCommandLineArguments(args);
+    }
+    else if (args.size() == 1 && STARTS_WITH(args[0].c_str(), "--help-doc="))
+    {
+        m_helpDocCategory = args[0].substr(strlen("--help-doc="));
+        return GDALAlgorithm::ParseCommandLineArguments({"--help-doc"});
+    }
 
     for (const auto &arg : args)
     {
@@ -386,22 +393,47 @@ bool GDALRasterPipelineAlgorithm::ParseCommandLineArguments(
 std::string GDALRasterPipelineAlgorithm::GetUsageForCLI(
     bool shortUsage, const UsageOptions &usageOptions) const
 {
+    UsageOptions stepUsageOptions;
+    stepUsageOptions.isPipelineStep = true;
+
+    if (!m_helpDocCategory.empty() && m_helpDocCategory != "main")
+    {
+        auto alg = GetStepAlg(m_helpDocCategory);
+        std::string ret;
+        if (alg)
+        {
+            alg->SetCallPath({m_helpDocCategory});
+            alg->GetArg("help-doc")->Set(true);
+            return alg->GetUsageForCLI(shortUsage, stepUsageOptions);
+        }
+        else
+        {
+            fprintf(stderr, "ERROR: unknown pipeline step '%s'\n",
+                    m_helpDocCategory.c_str());
+            return CPLSPrintf("ERROR: unknown pipeline step '%s'\n",
+                              m_helpDocCategory.c_str());
+        }
+    }
+
     std::string ret = GDALAlgorithm::GetUsageForCLI(shortUsage, usageOptions);
     if (shortUsage)
         return ret;
 
     ret += "\n<PIPELINE> is of the form: read [READ-OPTIONS] "
            "( ! <STEP-NAME> [STEP-OPTIONS] )* ! write [WRITE-OPTIONS]\n";
+
+    if (m_helpDocCategory == "main")
+    {
+        return ret;
+    }
+
     ret += '\n';
     ret += "Example: 'gdal raster pipeline --progress ! read in.tif ! \\\n";
     ret += "               reproject --dst-crs=EPSG:32632 ! ";
     ret += "write out.tif --overwrite'\n";
     ret += '\n';
     ret += "Potential steps are:\n";
 
-    UsageOptions stepUsageOptions;
-    stepUsageOptions.isPipelineStep = true;
-
     for (const std::string &name : m_stepRegistry.GetNames())
     {
         auto alg = GetStepAlg(name);

apps/gdalalg_raster_pipeline.h

@@ -107,6 +107,9 @@ class GDALRasterPipelineAlgorithm final
     {
         return m_outputDataset;
     }
+
+  private:
+    std::string m_helpDocCategory{};
 };
 
 //! @endcond

apps/gdalalg_vector_pipeline.cpp

@@ -207,7 +207,14 @@ bool GDALVectorPipelineAlgorithm::ParseCommandLineArguments(
 {
     if (args.size() == 1 && (args[0] == "-h" || args[0] == "--help" ||
                              args[0] == "help" || args[0] == "--json-usage"))
+    {
         return GDALAlgorithm::ParseCommandLineArguments(args);
+    }
+    else if (args.size() == 1 && STARTS_WITH(args[0].c_str(), "--help-doc="))
+    {
+        m_helpDocCategory = args[0].substr(strlen("--help-doc="));
+        return GDALAlgorithm::ParseCommandLineArguments({"--help-doc"});
+    }
 
     for (const auto &arg : args)
     {
@@ -459,22 +466,47 @@ bool GDALVectorPipelineAlgorithm::ParseCommandLineArguments(
 std::string GDALVectorPipelineAlgorithm::GetUsageForCLI(
     bool shortUsage, const UsageOptions &usageOptions) const
 {
+    UsageOptions stepUsageOptions;
+    stepUsageOptions.isPipelineStep = true;
+
+    if (!m_helpDocCategory.empty() && m_helpDocCategory != "main")
+    {
+        auto alg = GetStepAlg(m_helpDocCategory);
+        std::string ret;
+        if (alg)
+        {
+            alg->SetCallPath({m_helpDocCategory});
+            alg->GetArg("help-doc")->Set(true);
+            return alg->GetUsageForCLI(shortUsage, stepUsageOptions);
+        }
+        else
+        {
+            fprintf(stderr, "ERROR: unknown pipeline step '%s'\n",
+                    m_helpDocCategory.c_str());
+            return CPLSPrintf("ERROR: unknown pipeline step '%s'\n",
+                              m_helpDocCategory.c_str());
+        }
+    }
+
     std::string ret = GDALAlgorithm::GetUsageForCLI(shortUsage, usageOptions);
     if (shortUsage)
         return ret;
 
     ret += "\n<PIPELINE> is of the form: read [READ-OPTIONS] "
            "( ! <STEP-NAME> [STEP-OPTIONS] )* ! write [WRITE-OPTIONS]\n";
+
+    if (m_helpDocCategory == "main")
+    {
+        return ret;
+    }
+
     ret += '\n';
     ret += "Example: 'gdal vector pipeline --progress ! read in.gpkg ! \\\n";
     ret += "               reproject --dst-crs=EPSG:32632 ! ";
     ret += "write out.gpkg --overwrite'\n";
     ret += '\n';
     ret += "Potential steps are:\n";
 
-    UsageOptions stepUsageOptions;
-    stepUsageOptions.isPipelineStep = true;
-
     for (const std::string &name : m_stepRegistry.GetNames())
     {
         auto alg = GetStepAlg(name);

apps/gdalalg_vector_pipeline.h

@@ -110,6 +110,9 @@ class GDALVectorPipelineAlgorithm final
     {
         return m_outputDataset;
     }
+
+  private:
+    std::string m_helpDocCategory{};
 };
 
 /************************************************************************/

apps/gdalargumentparser.cpp

@@ -43,6 +43,18 @@ GDALArgumentParser::GDALArgumentParser(const std::string &program_name,
                 })
             .help(_("Shows short help message and exits."));
 
+        // Used by program-output directives in .rst files
+        add_argument("--help-doc")
+            .flag()
+            .hidden()
+            .action(
+                [this](const auto &)
+                {
+                    std::cout << usage() << std::endl;
+                    std::exit(0);
+                })
+            .help(_("Display help message for use by documentation."));
+
         add_argument("--long-usage")
             .flag()
             .action(

apps/gdalargumentparser.h

@@ -73,7 +73,7 @@ class GDALArgumentParser : public ArgumentParser
     //! Format an exception as an error message and display the program usage
     void display_error_and_usage(const std::exception &err);
 
-    //! Add -q/--quiet argument, and store its value in *pVar (if pVar not null)
+    //! Add -q/\--quiet argument, and store its value in *pVar (if pVar not null)
     Argument &add_quiet_argument(bool *pVar);
 
     //! Add "-if format_name" argument for input format, and store its value into *pvar.

apps/gdaltransform.cpp

@@ -34,20 +34,25 @@
 /*                               Usage()                                */
 /************************************************************************/
 
-static void Usage(bool bIsError, const char *pszErrorMsg = nullptr)
+static void Usage(bool bIsError, const char *pszErrorMsg = nullptr,
+                  bool bHelpDoc = false)
 
 {
     fprintf(bIsError ? stderr : stdout,
             "Usage: gdaltransform [--help] [--help-general]\n"
-            "    [-i] [-s_srs <srs_def>] [-t_srs <srs_def>] [-to "
-            ">NAME>=<VALUE>]...\n"
-            "    [-s_coord_epoch <epoch>] [-t_coord_epoch <epoch>]\n"
-            "    [-ct <proj_string>] [-order <n>] [-tps] [-rpc] [-geoloc] \n"
-            "    [-gcp <pixel> <line> <easting> <northing> [elevation]]...\n"
-            "    [-output_xy] [-E] [-field_sep <sep>] [-ignore_extra_input]\n"
-            "    [<srcfile> [<dstfile>]]\n"
-            "\n");
-
+            "       [-i] [-s_srs <srs_def>] [-t_srs <srs_def>] "
+            "[-to >NAME>=<VALUE>]...\n"
+            "       [-s_coord_epoch <epoch>] [-t_coord_epoch <epoch>]\n"
+            "       [-ct <proj_string>] [-order <n>] [-tps] [-rpc] [-geoloc] \n"
+            "       [-gcp <pixel> <line> <easting> <northing> [elevation]]...\n"
+            "       [-output_xy] [-E] [-field_sep <sep>] "
+            "[-ignore_extra_input]\n"
+            "       [<srcfile> [<dstfile>]]\n");
+
+    if (bHelpDoc)
+        exit(0);
+
+    fprintf(bIsError ? stderr : stdout, "\n");
     if (pszErrorMsg != nullptr)
         fprintf(stderr, "\nFAILURE: %s\n", pszErrorMsg);
 
@@ -146,6 +151,10 @@ MAIN_START(argc, argv)
         {
             Usage(false);
         }
+        else if (EQUAL(argv[i], "--help-doc"))
+        {
+            Usage(false, nullptr, true);
+        }
         else if (EQUAL(argv[i], "-t_srs"))
         {
             CHECK_HAS_ENOUGH_ADDITIONAL_ARGS(1);