Merge pull request #195 from hytechimaging/doc

Doc

data/observers.csv

@@ -0,0 +1 @@
+observer,firstName,lastName,organisation,contact

data/survey.csv

@@ -0,0 +1 @@
+region,survey,computer,shipName,cycle,session

data/transect.csv

@@ -0,0 +1 @@
+transect;strate;subRegion;length;wkt

doc/source/interface.rst

@@ -57,11 +57,18 @@ This button allows to open the settings dialog, to configure administrators tabl
 
 |
 
-`Survey`, `Transect` and `Strate` buttons open the single entity of their table
-which can be modified to fulfill the session metadata.
+`Survey` button opens the single entity of the table which can be modified to
+fulfill the session metadata. In the `Survey` table, `survey` attribute list
+values come from the `SurveyType` table, `shipName` attribute list values come
+from the `Boat` table.
 
-`Boat` and `Plateform` buttons open their tables dialog as each can contains more
-than one entity.
+`SurveyType`, `Transect`, `Boat` and `Plateform` buttons open their tables
+dialog as each can contains more than one entity.
+
+Espiecially for `Transect` table, it is possible to import a linear layer
+(EPSG:4326). The imported layer must have the same attribute names as the
+`Transect` table (transect,strate,subRegion,length). Transect entity reference
+will be available in the `Environment` table.
 
 3 - |save| Validation button
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -113,6 +120,8 @@ data from two distinct session. The environment/sighting/follower tables will be
 merging, avoiding to copy identical entities captured on a previous day. Gps point
 will be also decimated to keep only one record per minutes.
 
+User can use the gps checkboxes to choose which session gps layer will be kept.
+
 6 - |environment| Environment button
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -201,18 +210,16 @@ A status will be assigned automatically to each entity.
 The first status will be ``Begin``, then ``Add`` status will be created for the
 next entities until user changes the ``routeType`` attribute. User creates
 ``Add`` entities if the environmental variables change during the route. When the
-user changes the ``routeType`` attributes, it duplicates the previous entity
-(``Begin`` or ``Add`` status) and assignes the ``End`` status to the duplica.
-Environment status are check before the validation. A dialog should pop-up if 
-there is a missing ``Start`` / ``End`` record to inform user. Use the duplicate
-action to fix it (cf. :ref:`duplicateaction`).
+user changes the ``routeType`` attributes, the status attribute will be update to
+``Begin``. Entities with ``End`` status will be created only on export.
 
 .. _sightingtable:
 
 12 - Sighting table
 ~~~~~~~~~~~~~~~~~~~~
 
-The sighting table is used to modify sighting entity attributes. Sighting entity describes an observation made by the operator.
+The sighting table is used to modify sighting entity attributes.
+Sighting entity describes an observation made by the operator.
 
 13 - Map canvas
 ~~~~~~~~~~~~~~~
@@ -223,6 +230,8 @@ displayed:
 .. |gps_symbol| image:: images/gps.svg
   :width: 18
 
+.. |transect_symbol| image:: images/transect.svg
+
 .. |environment_symbol| image:: ../../images/environment_symbol.svg
   :width: 18
 
@@ -233,7 +242,8 @@ displayed:
   :width: 18
 
 - world (as background map)
-- |gps_symbol| gps 
+- |gps_symbol| gps
+- |transect_symbol| transect
 - |environment_symbol| environmenent 
 - |sighting_symbol| sighting 
 - |follower_symbol| follower 

doc/source/session.rst

@@ -8,9 +8,16 @@ Session
 
 Sammo-boat integrates a session system to works properly. To create a new session
 or load a existing session, user clicks on the |session| button in the
-Sammo-boat toolbar (cf. :ref:`sessionbutton`). User will select a folder in the dialog. If there is already
-a `sammo-boat.gpkg` database in the folder, this session will be opened.
+Sammo-boat toolbar (cf. :ref:`sessionbutton`). User will select a folder in the
+dialog.
+
+If there is already a `sammo-boat.gpkg` database in the folder, this session
+will be opened.
+
 Otherwise a new database will be created in the folder with the needed table.
+Notice that administrator and auxiliary tables can be populated by csv files,
+if there are located in the data folder.
+
 
 Database
 --------
@@ -24,22 +31,42 @@ to look at the database tables.
 
 |
 
-Some tables are administrator tables and should be populated with the survey information
-by an administrator :
+Some tables are administrator tables and should be populated with the survey
+information by an administrator. These tables can be fulfilled using the
+settings interface (cf. :ref:`settingsbutton`) or with csv files during the
+database initialization :
+
+.. list-table:: Administrator tables
+
+  * - **Table**
+    - **csv file**
+  * - survey
+    - survey.csv 
+  * - survey_type
+    - survey_type.csv
+  * - transect
+    - transect.csv   
+  * - boat
+    - boat.csv
+  * - plateform
+    - plateform.csv
+
+There is also three auxiliary tables that can be fulfilled with csv files :
 
-- survey
-- boat
-- plateform
-- strate
-- transect
-- observers
-- species
+.. list-table:: Auxiliary tables
+
+  * - **Table**
+    - **csv file**
+  * - observers
+    - observers.csv
+  * - species
+    - species.csv
+  * - behaviour_species
+    - behav.csv
 
 .. |settings| image:: ../../images/settings.png
   :height: 18
 
-Most of these tables can be configured in the settings dialog (cf. :ref:`settingsbutton`)
-
 The main tables used by operator will be the following:
 
 - environment
@@ -51,4 +78,9 @@ and the world table is only here to provide a map background.
 
 .. warning::
   Do not alter tables by removing fields or your database may become 
-  unusable in the Sammo-boat plugin.
+  unusable in the Sammo-boat plugin.
+
+
+Here is the full UML diagram of the database:
+
+.. image:: images/uml_diagram.png

sammo.py

@@ -5,11 +5,12 @@
 
 import os.path
 import platform
-from datetime import datetime
+from pathlib import Path
 from typing import Optional
+from datetime import datetime
 
-from qgis.PyQt.QtCore import Qt
-from qgis.PyQt.QtGui import QKeySequence
+from qgis.PyQt.QtCore import Qt, QUrl
+from qgis.PyQt.QtGui import QKeySequence, QDesktopServices, QIcon
 from qgis.PyQt.QtWidgets import QToolBar, QShortcut, QTableView, QAction
 
 from qgis.core import (
@@ -57,6 +58,8 @@ def __init__(self, iface):
 
         self.sessionAction = self.createSessionAction()
         self.settingsAction = self.createSettingsAction()
+        self.helpAction = self.createHelpAction()
+        self.toolbar.addSeparator()
         self.saveAction = self.createSaveAction()
         self.exportAction = self.createExportAction()
         self.mergeAction = self.createMergeAction()
@@ -203,6 +206,13 @@ def createSettingsAction(self) -> SammoSettingsAction:
         )
         return button
 
+    def createHelpAction(self) -> QAction:
+        button = QAction(QIcon("images/help.png"), "Help")
+        button.setToolTip("Help")
+        button.triggered.connect(self.openHelp)
+        self.toolbar.addAction(button)
+        return button
+
     def createMergeAction(self) -> SammoSessionAction:
         button = SammoMergeAction(self.mainWindow, self.toolbar)
         button.triggered.connect(self.onMergeAction)
@@ -264,6 +274,19 @@ def initShortcuts(self) -> None:
         )
         self.zoomOutShortcut.activated.connect(self.iface.mapCanvas().zoomOut)
 
+    def openHelp(self):
+        QDesktopServices.openUrl(
+            QUrl.fromLocalFile(
+                (
+                    Path(__file__).parent /
+                    "doc" /
+                    "build" /
+                    "html" /
+                    "index.html"
+                ).as_posix()
+            )
+        )
+
     def unload(self):
         self.activateGPS()  # add End environment Status if needed
         self.gpsReader.stop()

src/core/database.py

@@ -84,9 +84,10 @@ def init(self, directory: str) -> bool:
             self._createFieldsForGpsTable(), GPS_TABLE, QgsWkbTypes.Point
         )
 
-        self._createTable(self._fieldsObserver(), OBSERVERS_TABLE)
-
+
         # administrator table
+        self._createTable(self._fieldsObserver(), OBSERVERS_TABLE)
+        self._populateTable(SPECIES_TABLE, "observers.csv")
         self._createTable(self._createFieldsForSpeciesTable(), SPECIES_TABLE)
         self._populateTable(SPECIES_TABLE, "species.csv")
         self._createTable(

src/gui/ui/settings.ui

@@ -7,7 +7,7 @@
     <x>0</x>
     <y>0</y>
     <width>400</width>
-    <height>273</height>
+    <height>244</height>
    </rect>
   </property>
   <property name="windowTitle">
@@ -51,6 +51,9 @@
             <height>16777215</height>
            </size>
           </property>
+          <property name="toolTip">
+           <string>Import</string>
+          </property>
           <property name="text">
            <string/>
           </property>