Merge pull request #895 from opengisch/documentation-updates

Documentation Updates
opengisch · Mar 28, 2024 · 7351d0e · 7351d0e
2 parents 2918dbf + 7a2b0cb
commit 7351d0e
Show file tree

Hide file tree

Showing 35 changed files with 364 additions and 65 deletions.
diff --git a/docs/docs/assets/menu.png b/docs/docs/assets/menu.png
diff --git a/docs/docs/assets/plugin_manager.png b/docs/docs/assets/plugin_manager.png
diff --git a/docs/docs/assets/toolbar.png b/docs/docs/assets/toolbar.png
diff --git a/docs/docs/assets/usabilityhub-abstract-metaconfig.png b/docs/docs/assets/usabilityhub-abstract-metaconfig.png
diff --git a/docs/docs/assets/usabilityhub-abstract-modelselection.png b/docs/docs/assets/usabilityhub-abstract-modelselection.png
diff --git a/docs/docs/assets/usabilityhub-abstract-projecttopping.png b/docs/docs/assets/usabilityhub-abstract-projecttopping.png
diff --git a/docs/docs/assets/usabilityhub-abstract-referenceddata.png b/docs/docs/assets/usabilityhub-abstract-referenceddata.png
diff --git a/docs/docs/assets/usabilityhub-abstract-toppingdownload.png b/docs/docs/assets/usabilityhub-abstract-toppingdownload.png
diff --git a/docs/docs/assets/usabilityhub-exporter-additive-settings.png b/docs/docs/assets/usabilityhub-exporter-additive-settings.png
diff --git a/docs/docs/assets/usabilityhub-exporter-generated.png b/docs/docs/assets/usabilityhub-exporter-generated.png
diff --git a/docs/docs/assets/usabilityhub-exporter-ili2db.png b/docs/docs/assets/usabilityhub-exporter-ili2db.png
diff --git a/docs/docs/assets/usabilityhub-exporter-layer-styleicon.png b/docs/docs/assets/usabilityhub-exporter-layer-styleicon.png
diff --git a/docs/docs/assets/usabilityhub-exporter-layer.png b/docs/docs/assets/usabilityhub-exporter-layer.png
diff --git a/docs/docs/assets/usabilityhub-exporter-model.png b/docs/docs/assets/usabilityhub-exporter-model.png
diff --git a/docs/docs/assets/usabilityhub-exporter-project.png b/docs/docs/assets/usabilityhub-exporter-project.png
diff --git a/docs/docs/assets/usabilityhub-exporter-reference.png b/docs/docs/assets/usabilityhub-exporter-reference.png
diff --git a/docs/docs/assets/usabilityhub-exporter-repo.png b/docs/docs/assets/usabilityhub-exporter-repo.png
diff --git a/docs/docs/assets/usabilityhub-exporter-target.png b/docs/docs/assets/usabilityhub-exporter-target.png
diff --git a/docs/docs/assets/usabilityhub_exporter_target.png b/docs/docs/assets/usabilityhub_exporter_target.png
diff --git a/docs/docs/assets/validation_exportmodels.png b/docs/docs/assets/validation_exportmodels.png
diff --git a/docs/docs/assets/workflow_wizard_export_data_base.png b/docs/docs/assets/workflow_wizard_export_data_base.png
diff --git a/docs/docs/assets/workflow_wizard_intro.png b/docs/docs/assets/workflow_wizard_intro.png
diff --git a/docs/docs/assets/workflow_wizard_schema_import_linked_models.png b/docs/docs/assets/workflow_wizard_schema_import_linked_models.png
diff --git a/docs/docs/background_info/faq.md b/docs/docs/background_info/faq.md
@@ -0,0 +1,7 @@
+<!---
+this page is not (yet) published. Here we collect stuff that should be noted somewhere, but is not documented.
+--->
+
+Q: Why t_basket columns are created for `STRUCTURE` tables? Since those entries belong to objects anyway, they have already the basket of the owner object.
+
+A: So it's easier (e.g. for ili2db) to delete all data of a basket...
diff --git a/docs/docs/background_info/meta_attributes.md b/docs/docs/background_info/meta_attributes.md
@@ -57,8 +57,11 @@ Some additional non standard meta attributes are understood by the Model Baker a
 ### List of specific Attributes
 
 - **qgis.modelbaker.dispExpression**
-Used as the display expression for a layer. The display expression is the *name* that is used to identify a feature by text. One of the places where this is used is the combobox that is shown for a Relation Reference Widget on feature forms. ![relation reference](../assets/meta_attributes_relation_reference.png)
 
+  Used as the display expression for a layer. The display expression is the *name* that is used to identify a feature by text. One of the places where this is used is the combobox that is shown for a Relation Reference Widget on feature forms. ![relation reference](../assets/meta_attributes_relation_reference.png)
+- **qgis.modelbaker.formOrder**
+
+  Used to define the order of the attributes in the form like `[email protected]=1`. If you define the order of an attribute, all other attributes in the class will have a lower priority, what means when you set the order for one single attribute (the value doesn't matter) it will appear as the first attribute in the corresponding form.
 
 ## Extra Meta Attribute File
 

diff --git a/docs/docs/background_info/usabilityhub/modelbaker_integration.md b/docs/docs/background_info/usabilityhub/modelbaker_integration.md
@@ -1,24 +1,9 @@
-According to a model name, paths to *metaconfiguration files* are found in *ilidata.xml*. These *metaconfiguration files* contain, besides configuration parameters, *DatasetMetadata-Ids*. Based on these *DatasetMetadata-Ids* the paths to the *Toppingfiles* are found in the *ilidata.xml*.
+## Metaconfiguration
 
-> Other tools might use a different workflow. For example, the *ili2db* is passed the *metaconfiguration file*. There in the *metaconfiguration* then also the model is defined.
-
-![uml](../../assets/usabilityhub_uml_modelbaker.png)
-
-#### Workflow
-1. The user enters the model name in the [dialog](../../../user_guide/import_workflow/#metaconfiguration-topping).
-2. The *ilidata.xml* is parsed for links to *metaconfiguration files* according to the model name.
-3. The user selects a *metaconfiguration file*.
-4. The *metaconfiguration file* is downloaded.
-4. The configurations are read from the *metaconfiguration file*.
-5. The configurations are considered in the creation of the physical model.
-6. The DatasetMetadata-Ids to the *topping files* are read from the *metaconfiguration file*.
-7. The *ilidata.xml* is parsed for links to the  *topping files* based on the DatasetMetadata-Ids.
-8. The *topping files* are downloaded
-9. The information is read from the *topping files* and included in the generation of the QGIS project.
-
-## ili2db configuration
+... and how it's handled in Model Baker.
 
 ### General Handling
+
 ili2db configurations are defined in the *metaconfiguration file*.
 ```ini
 [ch.ehi.ili2db]
@@ -67,16 +52,20 @@ When this parameter is set the *Advanced Options* and *CRS* settings are disable
 ### Refrencing other INTERLIS models
 Using the ili2db settings, it is possible to reference other models from *metaconfiguration files*. If the setting contains the value `models=KbS_LV95_v1_4;KbS_Basis`, then this is also adjusted in the Model Baker input mask. Of course, a search for possible *metaconfiguration files* on UsabILIty Hub will be started again, according to the currently set models. See also for that [Multiple Models and their Toppings](#multiple-models-and-their-toppings).
 
-## Toppings and their Configuration
-*Topping files* are files that are referenced in the *metaconfiguration* or in other *topping files* like e.g. the *project topping file* and contain the configuration information of the GIS project or parts of it. So they can be form configurations, style attributes, legend tree structures as well as data files. Individual topping files can be used for each tool.
+## Toppings
+
+... and their configuration.
+
+*Topping files* are files that are referenced in the *metaconfiguration* or in other *topping files* like e.g. the *project topping file* and contain the configuration information of the GIS project or parts of it. So they can be form configurations, style attribute as well as the legend tree structure. Individual topping files can be used for each tool.
 
 The Model Baker supports these kinds of *topping files*:
 
 - Project topping files: `yaml` files for project settings like legend display, linking to layer configuration files and layer order
 - QML layer style: `qml` files for layer configurations
 - Layer definition: `qlr` files for layer definitions
-- Data files: `xtf`/`xml`/`itf` files for data import
+
 ### Project Topping (`yaml`)
+
 Information about the project like the layer tree, the layers in the layer tree and the display order may be contained in a *toppingfile*. The `DatasetMetadata-Id` of the file is defined in the *metaconfiguration file* via the parameter `qgis.modelbaker.projecttopping` (or the deprecated `qgis.modelbaker.layertree`).
 
 The file is written in `yaml`:
@@ -143,6 +132,7 @@ layerorder:
 ```
 
 #### Layertree
+
 The layertree is described using a tree structure in the `yaml` format.
 
 Top level entry is `layertree` (or outdated: `legend`). This entry is not shown in the legend.
@@ -173,6 +163,7 @@ The `yaml` file shown above results in a legend structure in *QGIS*.
 ![uml](../../assets/usabilityhub_qgis_legend.png)
 
 ##### Renaming of layers
+
 Usually the existing layers are recognized by the names. This works fine for the most cases. But sometimes (e.g. when having an extended model with layers having the same name like the base model) the layers need to be recognized by other parameters. This gives the possiblity to name the layer as you want.
 
 It recognizes layers from the database optionally by `tablename` and `geometrycolumn`. INTERLIS based layers can be identified by the `iliname` as well. It takes the first match of `tablename` or `iliname` and otherwise it looks for the layername.
@@ -201,6 +192,7 @@ See the example:
     Be aware that relations loaded over qml style files rely on the layer names. This means, that you have to be carefull when the style files have been exported with other layer names than defined in the YAML.
 
 #### Display Order
+
 The display order of the layers is defined as simple list:
 ```
 layer-order:
@@ -209,11 +201,13 @@ layer-order:
 ```
 
 #### Multiple Models with multiple Project Toppings
+
 Layers with the same data source will not be added twice when the project is regenerated. New layers and subgroups are - if possible - loaded into already existing groups. Otherwise geometry layers are added above and the groups "tables" and "domains" below.
 
 Thus legend structures from several *project topping files* are merged.
 
 ### Layer Properties Topping (`qml`)
+
 For layer properties like form configurations, symbology etc. `qml` files are loaded as *topping files*.
 
 *Right-click on the layer > Export > Save as QGIS Layer Style File...*
@@ -251,30 +245,14 @@ The `qlr` topping files are assigned directly in the layertree of the *project t
 
 !!! Note
     The datasource in the QLR file is relative. This means you have to be carefull with QLR files providing file based datasources.
-### Catalogs and transfer files
-Catalogs and transferfiles (and other `itf`/`xtf`/`xml` files) can also be loaded as *toppingfiles*. The `DatasetMetadata-Ids` are defined in the *Metaconfigurationfile* via the global parameter `ch.interlis.referenceData`. Multiple ids and file paths can be specified (separated by `;`).
 
-These data files are added to the list of files to import in the [wizard](../../../user_guide/import_workflow/#import-of-interlis-data).
+## Referenced Data
 
-## Multiple Models and their Toppings
-Currently, a list of "LegendeEintrag_PlanGewaesserschutz_V1_1;KbS_LV95_V1_4;KbS_Basis_V1_4" lists the *metaconfiguration files* for all these models.
-![multimodels](../../assets/usabilityhub_multimodels.png)
-But then only one can be selected. If you want to select multiple *metaconfiguration files*, you have to import the models one after the other.
-
-### Best Practice
-It is best to make a *metaconfiguration file* that applies to the import of all models you usually choose. And to make the whole thing even more convenient, you can also configure the additional model in the *metaconfiguration file*.
-If a *metaconfiguration file* is valid for the import of both models "KbS_LV95_V1_4;KbS_Basis_V1_4", you can also configure both models in it:
-```ini
-[ch.ehi.ili2db]
-models = KbS_Basis_V1_4;KbS_Basis_V1_4
-```
-Thus the *Metaconfigurations* is found by both model names and when reading in "KbS_LV95_V1_4;KbS_Basis_V1_4" is loaded into the input mask of the Model Baker.
-
-## Using a local repository
-It can be useful for testing purposes to be able to use a local repository. This is configured as a [custom model directory](../../../user_guide/plugin_configuration/#custom-model-directories). `ilidata.xml` and `ilimodels.xml` are searched and parsed in it.
+Catalogs and transferfiles (and other `itf`/`xtf`/`xml` files) can also be loaded. The `DatasetMetadata-Ids` are defined in the *Metaconfigurationfile* via the global parameter `ch.interlis.referenceData`. Multiple ids and file paths can be specified (separated by `;`).
 
+These data files are added to the list of files to import in the [wizard](../../../user_guide/import_workflow/#import-of-interlis-data).
 
-## Directly Referenced Catalogues
+### Directly Referenced Catalogues
 
 Catalogues can be linked directly in the ilidata.xml to the model names (without using a meta configuration file). Just add them as `referenceData` and add the model names in the `categories`.
 
@@ -325,3 +303,21 @@ But already before the data import, the Model Baker checks the UsabILIty Hub for
   </baskets>
 </DatasetIdx16.DataIndex.DatasetMetadata>
 ```
+
+## Multiple Models and their Toppings
+
+Currently, a list of "LegendeEintrag_PlanGewaesserschutz_V1_1;KbS_LV95_V1_4;KbS_Basis_V1_4" lists the *metaconfiguration files* for all these models.
+![multimodels](../../assets/usabilityhub_multimodels.png)
+But then only one can be selected. If you want to select multiple *metaconfiguration files*, you have to import the models one after the other.
+
+### Best Practice
+It is best to make a *metaconfiguration file* that applies to the import of all models you usually choose. And to make the whole thing even more convenient, you can also configure the additional model in the *metaconfiguration file*.
+If a *metaconfiguration file* is valid for the import of both models "KbS_LV95_V1_4;KbS_Basis_V1_4", you can also configure both models in it:
+```ini
+[ch.ehi.ili2db]
+models = KbS_Basis_V1_4;KbS_Basis_V1_4
+```
+Thus the *Metaconfigurations* is found by both model names and when reading in "KbS_LV95_V1_4;KbS_Basis_V1_4" is loaded into the input mask of the Model Baker.
+
+## Using a local repository
+It can be useful for testing purposes to be able to use a local repository. This is configured as a [custom model directory](../../../user_guide/plugin_configuration/#custom-model-directories). `ilidata.xml` and `ilimodels.xml` are searched and parsed in it.
diff --git a/docs/docs/background_info/usabilityhub/overview.md b/docs/docs/background_info/usabilityhub/overview.md
@@ -0,0 +1,114 @@
+## What is it about?
+
+With Model Baker ***additional information*** for models can be found automatically via the web.
+
+***Additional information*** such as:
+
+- ili2db settings ([Metaconfiguration](#metaconfiguration))
+- Data files, like catalogs ([Referenced Data](#referenced-data))
+- QGIS project configurations (so called [Toppings](#toppings))
+
+This means that complex configurations can be made *once* and used *multiple times*.
+
+### Metaconfiguration
+
+The metaconfiguration can be found before creating the physical data model on the *Schema Import Configuration* page.
+
+![metaconfig](../../assets/usabilityhub-abstract-metaconfig.png)
+
+The metaconfiguration can contain the ili2db settings as well as links to the required QGIS project configurations (toppings) and data files (referenced data).
+
+Find technical background and detailed information about the metaconfiguration [here](../modelbaker_integration/#metaconfiguration)
+
+### Referenced data
+
+The referenced data required for a model, such as catalogs and codelists, can be found in the *Data Import Configuration*.
+
+![referenced data](../../assets/usabilityhub-abstract-referenceddata.png)
+
+They may already have been linked via the [metaconfiguration](#metaconfiguration) before as well.
+
+Find technical background and detailed information about the referenced data integration [here](../modelbaker_integration/#referenced-data).
+
+### Toppings
+
+The QGIS project configurations or so called "toppings" can - if not already linked via the [metaconfiguration](#metaconfiguration) - be found each time on the *Project Generation* page via a "projecttopping" file.
+
+![projecttopping](../../assets/usabilityhub-abstract-projecttopping.png)
+
+The projecttopping defines general project configurations such as layertree, variables etc. and links to the required toppings such as layerstyle etc. which are then downloaded and applied when the project is generated.
+
+![topping download](../../assets/usabilityhub-abstract-toppingdownload.png)
+
+Find technical background and detailed information about the toppings [here](../modelbaker_integration/#toppings).
+
+## Where do those additional information come from?
+
+Just as we can now find INTERLIS models by searching the ilimodels.xml files on the repositories we can find this additional information via the `ilidata.xml` file.
+
+It filters the entries by the ***name*** of the used INTERLIS ***model***.
+
+More information about the technical background you can find [here](../../background_info/usabilityhub/technical_concept.md)
+
+## What are the Workflows?
+
+All these ***additional information*** are concernig a specific model. That's why they are found according to the selected model's name.
+
+![model selection](../../assets/usabilityhub-abstract-modelselection.png)
+
+### On choosing a metaconfiguration
+
+...that links to *referenced data* and a *projecttopping* the workflow looks like this:
+
+1. User enters the model name in the ***Source Selection***
+2. *ilidata.xml* is parsed for links to *metaconfiguration files* according to the model name
+3. User selects a *metaconfiguration*
+
+    ![metaconfig](../../assets/usabilityhub-abstract-metaconfig.png)
+
+4. *Metaconfiguration file* is downloaded and the ili2db settings are read from the *metaconfiguration*
+5. ili2db settings are considered in the creation of the physical model
+6. Links to the *referenced data* are read from the *metaconfiguration*
+7. *ilidata.xml* is parsed for links to the *referenced data*
+8. *Referenced data files* are downloaded and imported
+9. Links to the *projecttopping* is read from the *metaconfiguration*
+10. *ilidata.xml* is parsed for links to the *projecttopping*
+11. *Projecttopping file* is downloaded and links to the *other toppings* (like layerstyles etc.) is read from the *projecttopping*
+12. *ilidata.xml* is parsed for links to the *toppings*
+13. *Topping files* are downloaded
+14. The information is read from the *projettopping* and the linked *toppings* and included in the generation of the QGIS project
+
+### On choosing referenced data directly
+
+...from the repositories in the ***Data Import Configuration*** the steps are:
+
+1. *ilidata.xml* is parsed for links to the *referenced data* according to the model name.
+2. User selects *referenced data*
+
+    ![referenced data](../../assets/usabilityhub-abstract-referenceddata.png)
+
+3. *Referenced data files* are downloaded and imported
+
+!!! Note
+    The links to the *referenced data* are found according to the used model name.
+
+### On choosing project topping directly
+
+... from the repositories in ***Project Generation*** the steps are:
+
+1. *ilidata.xml* is parsed for links to the *projecttoppings* according to the model name
+2. User selects a *projecttopping*
+
+    ![projecttopping](../../assets/usabilityhub-abstract-projecttopping.png)
+
+3. *Projecttopping file* is downloaded and links to the *other toppings* (like layerstyles etc.) is read from the *projecttopping*
+4. *ilidata.xml* is parsed for links to the  *toppings*
+5. *Topping file* are downloaded
+6. The information is read from the *projettopping* and the linked *toppings* and included in the generation of the QGIS project.
+
+!!! Note
+    A *projecttopping* can be chosen from the local system as well.
+
+## How to make my own Toppings?
+
+This can be easily made with the [Model Baker Topping Exporter](../../user_guide/topping_exporter.md) from an exiting QGIS Project.
diff --git a/docs/docs/background_info/usabilityhub/technical_concept.md b/docs/docs/background_info/usabilityhub/technical_concept.md
@@ -1,5 +1,7 @@
-The idea of the UsabILIty Hub is to receive additional information for implemented INTERLIS models automatically via the web.
-Just as we can get models by linking the ilimodels.xml file from http://models.interlis.ch and the linked repositories, we can get the additional information with the ilidata.xml file on the UsabILIty Hub (currently https://models.opengis.ch) and the linked repositories.
+Just as we can now find INTERLIS models by searching the ilimodels.xml file from models.interlis.ch and the linked repositories, we can find additional information via the `ilidata.xml` file.
+
+!!! Note
+    The entry point is not models.interlis.ch but models.opengis.ch, which in turn links to models.interlis.ch.
 
 Settings for tools (like ili2db or Model Baker) are configured in a metaconfiguration file, as well as links to topping files that contain information about GIS project (such as symbologies or legend structures). Thus, this additional information usually consists of a metaconfiguration and any number of toppings.
 
@@ -90,7 +92,7 @@ In the UsabILIty Hub implementation of the Model Baker, the following types are
 #### Generic
 However, the content of the `Code_` element is not strictly defined. As long as it is a URL, it is up to the tool developer how she wants to use it.
 
-> At the moment the Model Baker does not use generic categories.
+> At the moment the Model Baker uses a generic category to know for what data source this topping is made for: `http://codes.modelbaker.ch/preferredDataSource` what can be `pg` and `gpkg`.
 
 ## The ilisite.xml
 The *ilisite.xml* is based on the model `IliSite09`. It contains the class (elements) `SiteMetadata` where URLs to other repositories are defined. These repositories in turn manage an *ilimodel.xml* or - likewise - an *ilidata.xml*.

diff --git a/docs/docs/background_info/usabilityhub/user_guide.md b/docs/docs/background_info/usabilityhub/user_guide.md
@@ -169,7 +169,7 @@ ili2db.mapping=MultiSurface
 #### Transfer files (e.g. Catalogs) (`xtf`/`xml`/`itf` Files)
 Transfer files such as catalogs can also be used as toppings. In the project *Nutzungsplanung_V310*, however, none were specified.
 
-For information and examples about the referencing of those files see in the [Model Baker Integration](../modelbaker_integration/#catalogs-and-transfer-files)
+For information and examples about the referencing of those files see in the [Model Baker Integration](../modelbaker_integration/#referenced-data)
 
 ### 3. Storage and Indexing of the Toppings