Implement relationship discovery for OGR layers, and show relationships in browser (Request in QGIS)

[qgis-bot]

Request for documentation

From pull request qgis/QGIS#49504
Author: @nyalldawson
QGIS version: 3.28

Implement relationship discovery for OGR layers, and show relationships in browser

PR Description:

(requires GDAL 3.6 or later!)

This PR implements two user-facing changes:

• it allows the Project Properties - Relations - Discover Relations feature to work for OGR layers which support relationships. Specifically, this includes GeoPackage (via the related tables extension) and ESRI FileGeodatabases
• it shows detailed relationship information for these data sources in the browser panel (see screenshot below)

I've included a bunch of related cleanups to the relationship classes in QGIS. There's two main parts to this:

1. A general cleanup including moving common enums to qgis.h and promoting to enum classes
2. An expansion of the QgsWeakRelation class, so that it is able to losslessly represent the full details of relationships available from the GDAL API (which was designed to be a "superset" of relationship properties from common formats)

The docs give a good breakdown on why this was added to QgsWeakRelation:

 * In constrast to QgsRelation, QgsWeakRelation can be used to encapsulate
 * information about a relationship which does not currently exist in a QGIS project.
 * E.g. it can be used to represent a relationship which exists in a database
 * backend (but not within a QGIS project). Accordingly, some properties
 * available in QgsWeakRelation are included for informational purposes only,
 * and cannot be translated to QgsRelations or respected in QGIS relationships.

So the primary distinction here is that a QgsWeakRelation represents a "theoretical" relationship from a datasource, whereas QgsRelation is the (lossy) functional version of that relationship in a QGIS project.

Commits tagged with [need-docs] or [FEATURE]

"[feature] Implement relationship discovery for OGR layers\n\n(requires GDAL 3.6 or later)\n\nThis change allows the Project Properties - Relations - Discover\nRelations feature to work for OGR layers which support relationships.\nSpecifically, this includes GeoPackage (via the related tables\nextension) and ESRI FileGeodatabases"