Merge pull request #10607 from rouault/doc_spelling

Add a 'make spelling' target to doc/

.github/workflows/doc_build.yml

@@ -85,11 +85,11 @@ jobs:
       run: |
         make latexpdf
       working-directory: ./doc
-    #- name: Spelling
-    #  shell: bash -l {0}
-    #  run: |
-    #    make spelling
-    #  working-directory: ./doc
+    - name: Spelling
+      shell: bash -l {0}
+      run: |
+        make spelling
+      working-directory: ./doc
     - uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4.3.3
       with:
         name: PDF

alg/gdalproximity.cpp

@@ -103,7 +103,7 @@ the proximity output.
 
   FIXED_BUF_VAL=n
 
-If this option is set, all pixels within the MAXDIST threadhold are
+If this option is set, all pixels within the MAXDIST threshold are
 set to this fixed value instead of to a proximity distance.
 */
 

alg/gdaltransformer.cpp

@@ -1765,13 +1765,13 @@ static void GDALGCPAntimeridianUnwrap(int nGCPCount, GDAL_GCP *pasGCPList,
  * a PROJ or WKT string, used as an override over the normally computed
  * pipeline. The pipeline must take into account the axis order of the source
  * and target SRS. <li> COORDINATE_EPOCH: (GDAL &gt;= 3.0) Coordinate epoch,
- * expressed as a decimal year. Useful for time-dependant coordinate operations.
+ * expressed as a decimal year. Useful for time-dependent coordinate operations.
  * </li>
  * <li> SRC_COORDINATE_EPOCH: (GDAL &gt;= 3.4) Coordinate epoch of source CRS,
- * expressed as a decimal year. Useful for time-dependant coordinate operations.
+ * expressed as a decimal year. Useful for time-dependent coordinate operations.
  * </li>
  * <li> DST_COORDINATE_EPOCH: (GDAL &gt;= 3.4) Coordinate epoch of target CRS,
- * expressed as a decimal year. Useful for time-dependant coordinate operations.
+ * expressed as a decimal year. Useful for time-dependent coordinate operations.
  * </li>
  * <li> GCPS_OK: If false, GCPs will not be used, default is TRUE.
  * </li>
@@ -3366,11 +3366,11 @@ void *GDALCreateReprojectionTransformer(const char *pszSrcWKT,
  * <li>COORDINATE_OPERATION=string: PROJ or WKT string representing a
  * coordinate operation, overriding the default computed transformation.</li>
  * <li>COORDINATE_EPOCH=decimal_year: Coordinate epoch, expressed as a
- * decimal year. Useful for time-dependant coordinate operations.</li>
+ * decimal year. Useful for time-dependent coordinate operations.</li>
  * <li> SRC_COORDINATE_EPOCH: (GDAL &gt;= 3.4) Coordinate epoch of source CRS,
- * expressed as a decimal year. Useful for time-dependant coordinate
+ * expressed as a decimal year. Useful for time-dependent coordinate
  *operations.</li> <li> DST_COORDINATE_EPOCH: (GDAL &gt;= 3.4) Coordinate epoch
- *of target CRS, expressed as a decimal year. Useful for time-dependant
+ *of target CRS, expressed as a decimal year. Useful for time-dependent
  *coordinate operations.</li>
  * </ul>
  *

alg/gdalwarper.cpp

@@ -1221,7 +1221,7 @@ CPLErr GDALWarpDstAlphaMasker(void *pMaskFuncArg, int nBandCount,
  * is sufficient.  Depending on the transformation in effect, the source
  * window may be a bit too small, or even missing large areas.  Problem
  * situations are those where the transformation is very non-linear or
- * "inside out".  Examples are transforming from WGS84 to Polar Steregraphic
+ * "inside out".  Examples are transforming from WGS84 to Polar Stereographic
  * for areas around the pole, or transformations where some of the image is
  * untransformable.  The following options provide some additional control
  * to deal with errors in computing the source window:

doc/CMakeLists.txt

@@ -13,7 +13,7 @@ if (UNIX
 else()
     set(BUILD_DOCS_DEFAULT OFF)
 endif()
-option(BUILD_DOCS "Set to ON to define documentation targets: 'html', 'latexpdf', 'man', 'doxygen', 'doxygen_check_warnings', 'clean_doc'" ${BUILD_DOCS_DEFAULT})
+option(BUILD_DOCS "Set to ON to define documentation targets: 'html', 'latexpdf', 'man', 'doxygen', 'doxygen_check_warnings', 'spelling', 'clean_doc'" ${BUILD_DOCS_DEFAULT})
 
 if (BUILD_DOCS)
     if (NOT UNIX)
@@ -59,6 +59,11 @@ if (BUILD_DOCS)
         COMMAND ${MAKE_EXECUTABLE} man BUILDDIR=${DOC_BUILDDIR}
         WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
 
+    add_custom_target(
+        spelling
+        COMMAND ${MAKE_EXECUTABLE} spelling BUILDDIR=${DOC_BUILDDIR}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
+
     add_custom_target(
         clean_doc
         COMMAND ${MAKE_EXECUTABLE} clean BUILDDIR=${DOC_BUILDDIR}

doc/Makefile

@@ -73,7 +73,7 @@ generated_rst_files: $(BUILDDIR)/.doxygen_up_to_date
 
 .PHONY: html latexpdf
 html: generated_rst_files
-	$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	BUILDDIR="${BUILDDIR}" $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	# Hack to hide the TOC
 	sed 's/<div class="toctree-wrapper compound">/<div class="toctree-wrapper compound" style="display: none;">/' < "$(BUILDDIR)/html/drivers/raster/index.html" > "$(BUILDDIR)/html/drivers/raster/index.html.mod"
 	mv "$(BUILDDIR)/html/drivers/raster/index.html.mod" "$(BUILDDIR)/html/drivers/raster/index.html"
@@ -89,10 +89,13 @@ html: generated_rst_files
 	cp -f "source/sponsors/Sustainable GDAL Sponsorship Prospectus.pdf" $(BUILDDIR)/html/sponsors
 
 man: generated_rst_files
-	$(SPHINXBUILD) -M man "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	BUILDDIR="${BUILDDIR}" $(SPHINXBUILD) -M man "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 latexpdf: generated_rst_files
-	$(SPHINXBUILD) -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	BUILDDIR="${BUILDDIR}" $(SPHINXBUILD) -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+spelling: generated_rst_files
+	BUILDDIR="${BUILDDIR}" $(SPHINXBUILD) -b spelling "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 clean:
 	rm -rf "$(BUILDDIR)/xml"

doc/source/conf.py

@@ -71,6 +71,7 @@
     "source_file",
     "sphinx.ext.napoleon",
     "sphinxcontrib.jquery",
+    "sphinxcontrib.spelling",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -516,7 +517,11 @@
 # -- Breathe -------------------------------------------------
 
 # Setup the breathe extension
-breathe_projects = {"api": "../build/xml"}
+
+build_dir = os.environ.get("BUILDDIR", "../build")
+if build_dir == "build":
+    build_dir = "../build"
+breathe_projects = {"api": os.path.join(build_dir, "xml")}
 breathe_default_project = "api"
 
 # Tell sphinx what the primary language being documented is.
@@ -533,3 +538,10 @@
 # -- Redirects --------------------------------------------------
 
 enable_redirects = False
+
+# -- Spelling --------------------------------------------------
+
+# Avoid running git
+spelling_ignore_contributor_names = False
+
+spelling_word_list_filename = ["spelling_wordlist.txt"]

doc/source/development/dev_documentation.rst

@@ -41,6 +41,11 @@ The following targets are available:
   verifies that there are no Doxygen warnings.
   Requires Doxygen >= 1.9.3 to be warning free.
 
+* ``spelling``: runs spell checking on the documentation, covering as well as
+  documentation generated from C/C++ API (Doxygen) and Python API. Words unknown
+  to the spell checker but still considered valid should be added to the allow
+  list in :file:`doc/source/spelling_wordlist.txt`
+
 * ``clean``: clean the ``doc/build`` directory.
 
 It is also possible to run those targets as CMake targets. In that case, the

doc/source/development/rfc/rfc19_safememalloc.rst

@@ -26,7 +26,7 @@ scanlines, whole image buffers, etc.. Currently no overflow checking is
 done, thus leading to potential allocation of not large enough buffers.
 Overflow can occur when raster dimensions are very large (this can be
 the case with a WMS raster source for example) or when a dataset is
-corrupted, intentionnaly or unintentionnaly. This can lead to latter
+corrupted, intentionally or unintentionally. This can lead to latter
 crash.
 
 This RFC introduces new API to allocate memory when the computation of

doc/source/development/rfc/rfc39_ogr_layer_algebra.rst

@@ -19,7 +19,7 @@ for commonly needed overlay analysis methods.
 The basic functionality for spatial analysis with GDAL is provided by
 GEOS. However, GEOS operates on geometries and typically people work
 with geospatial data layers. Vector data layers are represented in GDAL
-by OGRLayer objects. Thus, there is a need for spatial analaysis
+by OGRLayer objects. Thus, there is a need for spatial analysis
 operations that work on layers.
 
 Unfortunately there is no standard for spatial analysis operations API,

doc/source/development/rfc/rfc41_multiple_geometry_fields.rst

@@ -122,7 +122,7 @@ The OGRFeatureDefn class will be extended as the following :
            virtual void        AddGeomFieldDefn( OGRGeomFieldDefn * );
            virtual OGRErr      DeleteGeomFieldDefn( int iGeomField );
 
-           // Route OGRwkbGeometryType GetGeomType() and void SetGeomType() 
+           // Route OGRwkbGeometryType GetGeomType() and void SetGeomType()
            // on the first geometry field definition.
 
            // Same for IsGeometryIgnored() and SetGeometryIgnored()
@@ -179,7 +179,7 @@ The OGRFeature class will be extended as following :
            OGRErr              SetGeomFieldDirectly( int iField, OGRGeometry * );
            OGRErr              SetGeomField( int iField, OGRGeometry * );
 
-           // Route SetGeometryDirectly(), SetGeometry(), GetGeometryRef(), 
+           // Route SetGeometryDirectly(), SetGeometry(), GetGeometryRef(),
            // StealGeometry() on the first geometry field in the array
 
            // Modify implementation of SetFrom() to replicate all geometries
@@ -343,7 +343,7 @@ different in most use cases.
 
 (On the other side, if we introduce 64bit integer as a OGR type (this is
 an RFC that is waiting for implementation...), the above code would
-still produce a meaningful result. The string reprentation of a 64bit
+still produce a meaningful result. The string representation of a 64bit
 integer is not that bad as a default behavior.)
 
 GetFieldCount() would also take into account geometry fields, but in

doc/source/development/rfc/rfc46_gdal_ogr_unification.rst

@@ -264,7 +264,7 @@ Drivers and driver registration
      driver level because, in practice, layer creation options do not depend on the
      dataset instance.
      The value of this item is an XML snippet with a format similar to dataset creation
-     options. 
+     options.
      If specified, the passed creation options to CreateLayer() are validated
      against that authorized creation option list.
      Below an example of such an authorized open option list in the Shapefile driver.
@@ -305,17 +305,17 @@ Datasets / Datasources
 
        virtual int         TestCapability( const char * ) { return FALSE; }
 
-       virtual OGRLayer   *CreateLayer( const char *pszName, 
+       virtual OGRLayer   *CreateLayer( const char *pszName,
                                         OGRSpatialReference *poSpatialRef = NULL,
                                         OGRwkbGeometryType eGType = wkbUnknown,
                                         char ** papszOptions = NULL );
-       virtual OGRLayer   *CopyLayer( OGRLayer *poSrcLayer, 
-                                      const char *pszNewName, 
+       virtual OGRLayer   *CopyLayer( OGRLayer *poSrcLayer,
+                                      const char *pszNewName,
                                       char **papszOptions = NULL );
 
        virtual OGRStyleTable *GetStyleTable();
        virtual void        SetStyleTableDirectly( OGRStyleTable *poStyleTable );
-                               
+
        virtual void        SetStyleTable(OGRStyleTable *poStyleTable);
 
        virtual OGRLayer *  ExecuteSQL( const char *pszStatement,
@@ -337,7 +337,7 @@ Datasets / Datasources
    OGRLayerH CPL_DLL GDALDatasetGetLayer( GDALDatasetH, int );
    OGRLayerH CPL_DLL GDALDatasetGetLayerByName( GDALDatasetH, const char * );
    OGRErr    CPL_DLL GDALDatasetDeleteLayer( GDALDatasetH, int );
-   OGRLayerH CPL_DLL GDALDatasetCreateLayer( GDALDatasetH, const char *, 
+   OGRLayerH CPL_DLL GDALDatasetCreateLayer( GDALDatasetH, const char *,
                                          OGRSpatialReferenceH, OGRwkbGeometryType,
                                          char ** );
    OGRLayerH CPL_DLL GDALDatasetCopyLayer( GDALDatasetH, OGRLayerH, const char *,
@@ -383,7 +383,7 @@ Datasets / Datasources
 
 ::
 
-       virtual OGRLayer   *ICreateLayer( const char *pszName, 
+       virtual OGRLayer   *ICreateLayer( const char *pszName,
                                         OGRSpatialReference *poSpatialRef = NULL,
                                         OGRwkbGeometryType eGType = wkbUnknown,
                                         char ** papszOptions = NULL );
@@ -397,7 +397,7 @@ Datasets / Datasources
    creation option list (GDAL_DS_LAYER_CREATIONOPTIONLIST), before calling
    ICreateLayer() (this is similar to RasterIO() / IRasterIO() )
    A global pass on all in-tree OGR drivers has been made to rename CreateLayer()
-   as ICreateLayer(). 
+   as ICreateLayer().
 
 -  GDALOpenEx() is added to be able to open raster-only, vector-only, or
    raster-vector datasets. It accepts read-only/update mode,
@@ -533,7 +533,7 @@ Changes in drivers
    a file to determine if they recognize it. They have been converted to
    GDALDriver to accept a GDALOpenInfo argument and they now use its
    pabyHeader field to examine the first bytes of files. The number of
-   system calls realated to file access (open/stat), in order to
+   system calls related to file access (open/stat), in order to
    determine that a file is not recognized by any OGR driver, has now
    dropped from 46 in GDAL 1.11 to 1. The converted drivers are :
    AeronavFAA, ArcGEN, AVCBin, AVCE00, BNA, CSV, DGN, EDIGEO, ESRI

doc/source/development/rfc/rfc47_dataset_caching.rst

@@ -70,7 +70,7 @@ periods once the cache is full, and new memory is being initialized in
 GDALRasterBlock::Internalize().
 
 In order to remove the need for this LRU cache to be locked more often a
-new global config option is introducted "GDAL_DATASET_CACHING". This
+new global config option is added "GDAL_DATASET_CACHING". This
 causes the LRU cache to be per dataset when set to "YES", rather then a
 global cache ("NO" Default). Doing this will also allow threaded
 applications to flush only the cache for a single dataset, improving

doc/source/development/rfc/rfc52_strict_sql_quoting.rst

@@ -73,7 +73,7 @@ This change affects compatibility in the sense that users that relied on
 the current permissive behavior will have to adapt their SQL
 expressions. This might be quite tricky to detect as it will not always
 cause obvious runtime failures. For example " SELECT
-'i_thought_this_would_be_interpreted_as_a_column_name_but_now_it_is_a_string_litteral'
+'i_thought_this_would_be_interpreted_as_a_column_name_but_now_it_is_a_string_literal'
 FROM atable " will run without error but not produce the previously
 expected result. So applications will have to review how they build SQL
 filters ( SetAttributeFilter() ) and expressions ( ExecuteSQL() )

doc/source/development/rfc/rfc54_dataset_transactions.rst

@@ -96,7 +96,7 @@ MySQL
    other reading) because of the use of mysql_use_result() that can work
    with one single request at a time. mysql_store_result() would be a
    solution but requires ingesting the whole result set into memory,
-   which is inpractical for big layers.
+   which is impractical for big layers.
 -  step does not set row changes once the query has started (if done
    through another connection, because if done through ExecuteSQL() the
    long transaction is interrupted)
@@ -134,36 +134,36 @@ OGRDataSource which inherits from GDALDataset).
    /**
     \brief For datasources which support transactions, StartTransaction creates a transaction.
 
-    If starting the transaction fails, will return 
-    OGRERR_FAILURE. Datasources which do not support transactions will 
+    If starting the transaction fails, will return
+    OGRERR_FAILURE. Datasources which do not support transactions will
     always return OGRERR_UNSUPPORTED_OPERATION.
 
     Nested transactions are not supported.
-    
+
     All changes done after the start of the transaction are definitely applied in the
     datasource if CommitTransaction() is called. They may be canceled by calling
     RollbackTransaction() instead.
-    
+
     At the time of writing, transactions only apply on vector layers.
-    
+
     Datasets that support transactions will advertise the ODsCTransactions capability.
     Use of transactions at dataset level is generally preferred to transactions at
     layer level, whose scope is rarely limited to the layer from which it was started.
-    
+
     In case StartTransaction() fails, neither CommitTransaction() or RollbackTransaction()
     should be called.
-    
+
     If an error occurs after a successful StartTransaction(), the whole
     transaction may or may not be implicitly canceled, depending on drivers. (e.g.
     the PG driver will cancel it, SQLite/GPKG not). In any case, in the event of an
     error, an explicit call to RollbackTransaction() should be done to keep things balanced.
-    
+
     By default, when bForce is set to FALSE, only "efficient" transactions will be
     attempted. Some drivers may offer an emulation of transactions, but sometimes
     with significant overhead, in which case the user must explicitly allow for such
     an emulation by setting bForce to TRUE. Drivers that offer emulated transactions
     should advertise the ODsCEmulatedTransactions capability (and not ODsCTransactions).
-    
+
     This function is the same as the C function GDALDatasetStartTransaction().
 
     @param bForce can be set to TRUE if an emulation, possibly slow, of a transaction
@@ -182,10 +182,10 @@ OGRDataSource which inherits from GDALDataset).
    /**
     \brief For datasources which support transactions, CommitTransaction commits a transaction.
 
-    If no transaction is active, or the commit fails, will return 
-    OGRERR_FAILURE. Datasources which do not support transactions will 
-    always return OGRERR_UNSUPPORTED_OPERATION. 
-    
+    If no transaction is active, or the commit fails, will return
+    OGRERR_FAILURE. Datasources which do not support transactions will
+    always return OGRERR_UNSUPPORTED_OPERATION.
+
     Depending on drivers, this may or may not abort layer sequential readings that
     are active.
 
@@ -202,11 +202,11 @@ OGRDataSource which inherits from GDALDataset).
 
    /**
     \brief For datasources which support transactions, RollbackTransaction will roll
-    back a datasource to its state before the start of the current transaction. 
+    back a datasource to its state before the start of the current transaction.
 
-    If no transaction is active, or the rollback fails, will return  
+    If no transaction is active, or the rollback fails, will return
     OGRERR_FAILURE. Datasources which do not support transactions will
-    always return OGRERR_UNSUPPORTED_OPERATION. 
+    always return OGRERR_UNSUPPORTED_OPERATION.
 
     This function is the same as the C function GDALDatasetRollbackTransaction().
 
@@ -244,7 +244,7 @@ whose data is supported by files/directories.
 ::
 
    /** Returns a new datasource object that adds transactional behavior to an existing datasource.
-    * 
+    *
     * The provided poTransactionBehaviour object should implement driver-specific
     * behavior for transactions.
     *