Merge pull request #3832 from GeotrekCE/doc_improve_loadinfrastructur…

…e_command

Improve help and doc for the `loadinfrastructure` command

docs/changelog.rst

@@ -20,6 +20,10 @@ CHANGELOG
 - Fix cannot click on objects after customizing map styles (#3800)
 - Fix profile elevation PNG generation by using cairosvg instead of convertit (#3833)
 
+**Documentation**
+
+- Improve help and doc for the `loadinfrastructure` command
+
 
 2.101.3     (2023-10-26)
 ------------------------

docs/install/import.rst

@@ -460,57 +460,77 @@ Import Infrastructure
 
 ::
 
-    usage: manage.py loadinfrastructure [-h] [--use-structure] [--encoding ENCODING] [--name-field NAME_FIELD] [--type-field TYPE_FIELD] [--category-field CATEGORY_FIELD]
-                                        [--condition-field CONDITION_FIELD] [--structure-field STRUCTURE_FIELD] [--description-field DESCRIPTION_FIELD] [--year-field YEAR_FIELD]
-                                        [--type-default TYPE_DEFAULT] [--category-default CATEGORY_DEFAULT] [--name-default NAME_DEFAULT] [--condition-default CONDITION_DEFAULT]
-                                        [--structure-default STRUCTURE_DEFAULT] [--description-default DESCRIPTION_DEFAULT] [--eid-field EID_FIELD] [--year-default YEAR_DEFAULT]
-                                        [--version] [-v {0,1,2,3}] [--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color] [--skip-checks]
-                                        point_layer
-
-    Load a layer with point geometries in te structure model
+    usage: manage.py loadinfrastructure [-h] [--use-structure] [--encoding ENCODING]
+        [--name-field NAME_FIELD] [--name-default NAME_DEFAULT]
+        [--type-field TYPE_FIELD] [--type-default TYPE_DEFAULT]
+        [--category-field CATEGORY_FIELD] [--category-default CATEGORY_DEFAULT]
+        [--condition-field CONDITION_FIELD] [--condition-default CONDITION_DEFAULT]
+        [--structure-field STRUCTURE_FIELD] [--structure-default STRUCTURE_DEFAULT]
+        [--description-field DESCRIPTION_FIELD] [--description-default DESCRIPTION_DEFAULT]
+        [--year-field YEAR_FIELD] [--year-default YEAR_DEFAULT]
+        [--eid-field EID_FIELD]
+        [--version] [-v {0,1,2,3}] [--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback]
+        [--no-color] [--force-color] [--skip-checks]
+        point_layer
+
+    Load a layer with point geometries and import features as infrastructures objects
+    (expected formats: shapefile or geojson)
 
     positional arguments:
       point_layer
 
     optional arguments:
       -h, --help            show this help message and exit
-      --use-structure       Allow to use structure for condition and type of infrastructures
+      --use-structure
+                            If set the given (or default) structure is used to select or create
+                            conditions and types of infrastructures.
       --encoding ENCODING, -e ENCODING
                             File encoding, default utf-8
       --name-field NAME_FIELD, -n NAME_FIELD
-                            Base url
+                            The field to be imported as the `name` of the infrastructure
+      --name-default NAME_DEFAULT
+                            Default name for all infrastructures, fallback for entries without a name
       --type-field TYPE_FIELD, -t TYPE_FIELD
-                            Base url
-      --category-field CATEGORY_FIELD, -i CATEGORY_FIELD
-                            Base url
-      --condition-field CONDITION_FIELD, -c CONDITION_FIELD
-                            Base url
-      --structure-field STRUCTURE_FIELD, -s STRUCTURE_FIELD
-                            Base url
-      --description-field DESCRIPTION_FIELD, -d DESCRIPTION_FIELD
-                            Base url
-      --year-field YEAR_FIELD, -y YEAR_FIELD
-                            Base url
+                            The field to select or create the type value of the infrastructure
+                            (field `InfrastructureType.label`)
       --type-default TYPE_DEFAULT
-                            Default type of infrastructure, it will create the type if it doesn't exist
+                            Default type for all infrastructures, fallback for entries without a type.
+      --category-field CATEGORY_FIELD, -i CATEGORY_FIELD
+                            The field to select or create the type value of the infrastructure
+                            (field `InfrastructureType.type`)
       --category-default CATEGORY_DEFAULT
-                            Category by default for all infrastructures, B by default
-      --name-default NAME_DEFAULT
-                            Base url
+                            Default category for all infrastructures, "B" by default. Fallback for entries
+                            without a category
+      --condition-field CONDITION_FIELD, -c CONDITION_FIELD
+                            The field to select or create the condition value of the infrastructure
+                            (field `InfrastructureCondition.label`)
       --condition-default CONDITION_DEFAULT
-                            Default Condition for all infrastructures, it will create the condition if it doesn't exist
+                            Default condition for all infrastructures, fallback for entries without a category
+      --structure-field STRUCTURE_FIELD, -s STRUCTURE_FIELD
+                            The field to be imported as the structure of the infrastructure
       --structure-default STRUCTURE_DEFAULT
                             Default Structure for all infrastructures
+      --description-field DESCRIPTION_FIELD, -d DESCRIPTION_FIELD
+                            The field to be imported as the description of the infrastructure
       --description-default DESCRIPTION_DEFAULT
-                            Default description for all infrastructures
-      --eid-field EID_FIELD
-                            External ID field
+                            Default description for all infrastructures, fallback for entries
+                            without a description
+      --year-field YEAR_FIELD, -y YEAR_FIELD
+                            The field to be imported as the `implantation_year` of the infrastructure
       --year-default YEAR_DEFAULT
-                            Default year for all infrastructures
+                            Default year for all infrastructures, fallback for entries without a year
+      --eid-field EID_FIELD
+                            The field to be imported as the `eid` of the infrastructure (external ID)
       --version             show program's version number and exit
       -v {0,1,2,3}, --verbosity {0,1,2,3}
-                            Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
-      --settings SETTINGS   The Python path to a settings module, e.g. "myproject.settings.main". If this isn't provided, the DJANGO_SETTINGS_MODULE environment variable will be used.
+                            Verbosity level; 0=minimal output,
+                                1=normal output,
+                                2=verbose output,
+                                3=very verbose output
+      --settings SETTINGS
+                            The Python path to a settings module, e.g. "myproject.settings.main".
+                            If this isn't provided, the DJANGO_SETTINGS_MODULE environment variable
+                            will be used.
       --pythonpath PYTHONPATH
                             A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".
       --traceback           Raise on CommandError exceptions
@@ -519,6 +539,73 @@ Import Infrastructure
       --skip-checks         Skip system checks.
 
 
+Load a layer with point geometries and import entities as infrastructures objects.
+
+- expected formats for the `point_layer` file are shapefile or geojson (other geodjango supported-formats may work but untested),
+- the command updates existing Infrastructure objects based on the `eid` field (external ID),
+- if the Infrastructure object does not exist (or if `eid` is not specified) it is created.
+
+
+**Usage example**
+
+::
+
+    sudo geotrek loadinfrastructure \
+        --name-field "shpname" \
+        --type-field "shptype" \
+        --description-field "shpdesc" \
+        --year-field "shpyear" \
+        --eid-field "shpid" \
+        --condition-default "Badly damaged" \
+        --year-default "2023" \
+        --category-default "A" \
+        ./infrastructures_to_be_imported.shp
+
+- The command expects entries from `point_layer` file to have the the following fields: `shpname`, `shptype`, `shpdesc`, `shpyear` and `shpid`.
+- A default value is provided for the condition. It will be set for all imported infrastructures.
+- A default value is provided for the year in addition to the field mapping. In case the shapefile entry does not have a year attribute the command will take the default value instead.
+- The command will select or create InfrastructureType values based on the `type` argument, taking the default value "A" for the category.
+
+**Required fields**
+
+The following fields are mandatory to create an Infrastructure object: `name`, `type` and `category`. For each of those fields either an import field and/or a default value MUST be provided. If the command is unable to determine values for those fields for a given layer, the layer is skipped with an error message.
+
+**Default values**
+
+- When a default value is provided without a fieldname to import the default value is set for all Infrastructure objects.
+- When a default value is provided in addition to a fieldname to import it is used as a fallback for entries without the specified import field.
+
+**Selection and addition of parameterized values**
+
+Infrastructure objects have several values from Geotrek's parameterized values sets:
+
+- `type` from InfrastructureType values (and `category` which is implied by the `type` value),
+- `condition` from InfrastructureCondition values.
+
+New parameterized values are created and added to Geotrek Admin if necessary. The command checks if the imported `type` value already exists by looking for an InfrastructureType with the right `type` + `category`.
+
+::
+
+    sudo geotrek loadinfrastructure  --type-field "type"  --category-field "cat" [...]
+
+Selected or added InfrastructureType value:
+
+	- label <- value of `type` import field
+	- type <- value of `cat` import field
+	- optionnally if `--use-structure`: structure <- the structure value (import field or default)
+
+For InfrastructureCondition the check uses the `condition` argument.
+
+::
+
+    sudo geotrek loadinfrastructure  --condition-field "cond" [...]
+
+Selected or added InfrastructureCondition value:
+
+ 	- label <- value of `cond` field
+	- optionnally if `--use-structure`: structure <- the structure value (import field or default)
+
+
 Import Dive
 -----------
 

geotrek/infrastructure/management/commands/loadinfrastructure.py

@@ -15,38 +15,54 @@
 
 
 class Command(BaseCommand):
-    help = 'Load a layer with point geometries in te structure model\n'
+    help = (
+        "Load a layer with point geometries and import features as infrastructures objects "
+        "(expected formats: shapefile or geojson)"
+    )
     can_import_settings = True
     counter = 0
 
     def add_arguments(self, parser):
         parser.add_argument('point_layer')
         parser.add_argument('--use-structure', action='store_true', dest='use_structure', default=False,
-                            help='Allow to use structure for condition and type of infrastructures')
+                            help='If set the given (or default) structure is used to select or create '
+                                 'conditions and types of infrastructures.')
         parser.add_argument('--encoding', '-e', action='store', dest='encoding', default='utf-8',
                             help='File encoding, default utf-8')
-        parser.add_argument('--name-field', '-n', action='store', dest='name_field', help='Base url')
-        parser.add_argument('--type-field', '-t', action='store', dest='type_field', help='Base url')
-        parser.add_argument('--category-field', '-i', action='store', dest='category_field', help='Base url')
-        parser.add_argument('--condition-field', '-c', action='store', dest='condition_field', help='Base url')
-        parser.add_argument('--structure-field', '-s', action='store', dest='structure_field', help='Base url')
-        parser.add_argument('--description-field', '-d', action='store', dest='description_field', help='Base url')
-        parser.add_argument('--year-field', '-y', action='store', dest='year_field', help='Base url')
+        parser.add_argument('--name-field', '-n', action='store', dest='name_field',
+                            help='The field to be imported as the `name` of the infrastructure')
+        parser.add_argument('--name-default', action='store', dest='name_default',
+                            help='Default name for all infrastructures, fallback for entries without a name')
+        parser.add_argument('--type-field', '-t', action='store', dest='type_field',
+                            help='The field to select or create the type value of the infrastructure '
+                                 '(field `InfrastructureType.label`)')
         parser.add_argument('--type-default', action='store', dest='type_default',
-                            help="Default type of infrastructure, it will create the type if it doesn't exist")
+                            help="Default type for all infrastructures, fallback for entries without a type.")
+        parser.add_argument('--category-field', '-i', action='store', dest='category_field',
+                            help='The field to select or create the type value of the infrastructure '
+                                 '(field `InfrastructureType.type`)')
         parser.add_argument('--category-default', action='store', dest='category_default',
-                            help='Category by default for all infrastructures, B by default', default='B')
-        parser.add_argument('--name-default', action='store', dest='name_default', help='Base url')
+                            help='Default category for all infrastructures, "B" by default. Fallback for entries '
+                                 'without a category', default='B')
+        parser.add_argument('--condition-field', '-c', action='store', dest='condition_field',
+                            help='The field to select or create the condition value of the infrastructure '
+                                 '(field `InfrastructureCondition.label`)')
         parser.add_argument('--condition-default', action='store', dest='condition_default',
-                            help="Default Condition for all infrastructures, "
-                                 "it will create the condition if it doesn't exist")
+                            help="Default condition for all infrastructures, fallback for entries without a category")
+        parser.add_argument('--structure-field', '-s', action='store', dest='structure_field',
+                            help='The field to be imported as the structure of the infrastructure')
         parser.add_argument('--structure-default', action='store', dest='structure_default',
                             help='Default Structure for all infrastructures')
+        parser.add_argument('--description-field', '-d', action='store', dest='description_field',
+                            help='The field to be imported as the description of the infrastructure')
         parser.add_argument('--description-default', action='store', dest='description_default', default="",
-                            help='Default description for all infrastructures')
-        parser.add_argument('--eid-field', action='store', dest='eid_field', help='External ID field')
+                            help='Default description for all infrastructures, fallback for entries without a description')
+        parser.add_argument('--year-field', '-y', action='store', dest='year_field',
+                            help='The field to be imported as the `implantation_year` of the infrastructure')
         parser.add_argument('--year-default', action='store', dest='year_default',
-                            help='Default year for all infrastructures')
+                            help='Default year for all infrastructures, fallback for entries without a year')
+        parser.add_argument('--eid-field', action='store', dest='eid_field',
+                            help='The field to be imported as the `eid` of the infrastructure (external ID)')
 
     def handle(self, *args, **options):
         verbosity = options.get('verbosity')