Merge branch 'master' of gitlab-ssh.irstea.fr:theophile.terraz/pamhyr

doc/dev/documentation.org

@@ -28,20 +28,6 @@
 #+OPTIONS: toc:t
 #+LANGUAGE: UKenglish
 
-#+NAME: attr_wrap
-#+HEADER: :var width="\\textwidth"
-#+HEADER: :var caption=""
-#+HEADER: :var smallcaption=""
-#+HEADER: :var name=""
-#+HEADER: :var data=""
-#+HEADER: :var float="nil"
-#+BEGIN_SRC sh :results output :exports none
-  echo "#+CAPTION[$smallcaption]: $caption"
-  echo "#+NAME: $name"
-  echo "#+ATTR_LATEX: :width $width :float $float"
-  echo "$data"
-#+END_SRC
-
 #+BEGIN_abstract
 This document is for the use of developers. It describes the project
 architecture, the tools available to assist development and
@@ -54,13 +40,13 @@ documentation, translations or code.
 
 * Introduction
 
-Pamhyr2 is free and open source software (FOSS) graphical user
+{{{pamhyr2}}} is free and open source software (FOSS) graphical user
 interface (GUI) for 1D hydro-sedimentary modelling of rivers developed
 in Python (with version 3.8). It use PyQt at version 5 and matplotlib
 in version 3.4.1 or later for the user insterface (see
 {{{file(/requirements.txt)}}} for details). The architecture of
 project code follow the Qt Model/View architecture [fn:qt-arch] (see
-details in section [[Architecture]]). Pamhyr2 packages can be build
+details in section [[Architecture]]). {{{pamhyr2}}} packages can be build
 manually (see section [[Building packages]]), but there are automatically
 build with the gitlab-ci (see the section [[Setup the CI
 environment]]). Documentation files are written with org-mode[fn:org],
@@ -75,7 +61,7 @@ https://doc.qt.io/qt-5/model-view-programming.html (last access
 
 * Architecture
 
-Pamhyr2's architecture is based on Qt Model/View, see Figure
+{{{pamhyr2}}}'s architecture is based on Qt Model/View, see Figure
 [[graph-architecture]]. It is made up of several different components: the
 model (in blue), the graphical components (in red), the
 actions/delegates (in green), the commands (in purple), the solvers
@@ -178,7 +164,7 @@ https://doc.qt.io/qt-5/model-view-programming.html
 
 ** Model
 
-The model is a set of Python classes. In Pamhyr2, this classes must
+The model is a set of Python classes. In {{{pamhyr2}}}, this classes must
 respect some constraint. Each model class must inherits
 =Model.Tools.SQLSubModel= abstract class, except the =Model.Study=
 class who inherits =Model.Tools.SQLModel= (see [[SQL]]).
@@ -456,12 +442,12 @@ of Bar (Listing [[sql-bar]] and [[sql-foo]]).
               bar._sql_save(execute, data=data)
 #+end_src
 
-Let see the results database scheme for Pamhyr2 at version v0.0.7 in
+Let see the results database scheme for {{{pamhyr2}}} at version v0.0.7 in
 Figure [[sql_schema]].
 
 #+NAME: sql_schema
 #+ATTR_LATEX: :width 16cm
-#+CAPTION: SQLite database scheme at Pamhyr2 version v0.0.7 (generate with [[https://gitlab.com/Screwtapello/sqlite-schema-diagram]])
+#+CAPTION: SQLite database scheme at {{{pamhyr2}}} version v0.0.7 (generate with [[https://gitlab.com/Screwtapello/sqlite-schema-diagram]])
 [[./images/schema_v0.0.7.png]]
 
 
@@ -486,7 +472,7 @@ PamhyrModelList but use a dictionary instead of list.
 
 ** View
 
-Pamhyr2 use Qt as graphical user interface library with the
+{{{pamhyr2}}} use Qt as graphical user interface library with the
 application "Qt designer" for windows or widget creation (see [[UI file]])
 and "Qt linguist" for interface translate (see [[Translate]]). In
 addition, we use matplotlib as ploting library (see [[Plot]]).
@@ -501,11 +487,11 @@ componant translate, and possible other files or sub-directories.
 
 *** UI file
 
-We define as possible all Pamhyr2 windows and custom widgets with "Qt
-designer". This application generate UI file who describes interface
-organisation with table, layout, button, etc. This method is faster
-than hand made windows and widget creation, and saves us some purely
-descriptive code. The UI files are saved into =src/View/ui= for
+We define as possible all {{{pamhyr2}}} windows and custom widgets
+with "Qt designer". This application generate UI file who describes
+interface organisation with table, layout, button, etc. This method is
+faster than hand made windows and widget creation, and saves us some
+purely descriptive code. The UI files are saved into =src/View/ui= for
 window, and =/src/View/ui/Widgets= for custom widget.
 
 *** Translate
@@ -533,10 +519,11 @@ window, and =/src/View/ui/Widgets= for custom widget.
 
 *** Window
 
-The abstract class PamhyrWindow and PamhyrDialog are used for most of
-Pamhyr2 window. These class allow to create an window for Pamhyr2 GUI
-and implemente some useful methods. The super class method difine some
-generic value from optional parameters, for examples:
+The abstract class =PamhyrWindow= and =PamhyrDialog= are used for most
+of {{{pamhyr2}}} window. These class allow to create an window for
+{{{pamhyr2}}} GUI and implemente some useful methods. The super class
+method difine some generic value from optional parameters, for
+examples:
 - =self._study=: The study giving in constructor parameters =study=
   (typically a =Model.Study= class object)
 - =self._config=: The configuration giving in constructor parameters
@@ -546,7 +533,7 @@ generic value from optional parameters, for examples:
   object)
 
 #+NAME: window
-#+CAPTION: Example of Pamhyr2 window
+#+CAPTION: Example of {{{pamhyr2}}} window
 #+begin_src python :python python3 :results output :noweb yes
   from View.Tools.PamhyrWindow import PamhyrWindow
   from View.My.Translate import MyTranslate
@@ -593,7 +580,7 @@ window componants or connections.
 
 *** Table
 
-An abstract class PamhyrTableModel is available to define a simple
+An abstract class =PamhyrTableModel= is available to define a simple
 QAbstractTableModel shortly. In simple cases, there are only =data=
 and =setData= methode to implement, but the constructor needs more
 information than a classic QAbstractTableModel class.
@@ -654,7 +641,7 @@ class AddNodeCommand(QUndoCommand):
 
 All undo command must be push into a =QUndoStack= (see Listing
 [[undo-cmd-push]]) to perform the action and allow user undo and redo this
-action. In PamhyrWindow (and PamhyrDialog) the undo stack is
+action. In =PamhyrWindow= (and =PamhyrDialog=) the undo stack is
 automatically create if the option ="undo"= is activate at window
 creation, this stack is accessible at =self._undo_stack=.
 
@@ -672,7 +659,7 @@ creation, this stack is accessible at =self._undo_stack=.
 *** Plot
 
 To define a new plot you can create a class who inherit to
-PamhyrPlot. The creator need at leaste five argument:
+=PamhyrPlot=. The creator need at leaste five argument:
  - A =canvas= of type =MplCanvas=
  - A (optional) =trad= of type =PamhyrTranslate=
  - A =data= used in =draw= and =update= to create and update the plot
@@ -719,8 +706,8 @@ data has changed.
 
 ** Solver
 
-The Pamhyr2 architecture allow to define multiple solver. A solver is
-define by a:
+The {{{pamhyr2}}} architecture allow to define multiple solver. A
+solver is define by a:
  - type
  - name
  - description,
@@ -736,11 +723,11 @@ different solver type, this solver type implement the code for export
 study to solver input format, and read the solver output to study
 results. There exists a generic solver with a generic input and output
 format, the type could be use to use a solver not implemented in
-Pamhyr2, but this solver must can read/write input and output generic
-format or use external script. There is possible to define different
-solver with the same type, for example two differents version of the
-same solver. Finaly, with input and output formater is possible to
-execute a code on distant computer, for example, over ssh.
+{{{pamhyr2}}}, but this solver must can read/write input and output
+generic format or use external script. There is possible to define
+different solver with the same type, for example two differents
+version of the same solver. Finaly, with input and output formater is
+possible to execute a code on distant computer, for example, over ssh.
 
 #+name: graph-multi-solver
 #+header: :results drawer
@@ -857,8 +844,8 @@ solver and get results:
  - (2.1) The solver read the input file(s)
  - (2.2) The solver compute results and write it to solver output
    file(s)
- - (3) Pamhyr2 create a =Results= object
- - (3.1) The Pamhyr2 solver class read solver output file(s) and
+ - (3) {{{pamhyr2}}} create a =Results= object
+ - (3.1) The {{{pamhyr2}}} solver class read solver output file(s) and
    complete Results with readed data
 
 #+name: graph-pipeline
@@ -976,7 +963,7 @@ the temporal order of action is prensented in Figure
   }
 #+end_src
 
-To implement a Solver in Pamhyr2, there exists a abstract class
+To implement a Solver in {{{pamhyr2}}}, there exists a abstract class
 =Solver.AbstractSolver=. A class who herits this class, must implement
 different methods:
  - =export=: Export the study to solver input file(s)
@@ -987,7 +974,7 @@ different methods:
 
 ** Unit tests
 
-A very small part of Pamhyr2 has unit test. This part is limited to the Model.
+A very small part of {{{pamhyr2}}} has unit test. This part is limited to the Model.
 
 #+begin_src shell
   python3 -m venv test
@@ -1000,9 +987,9 @@ A very small part of Pamhyr2 has unit test. This part is limited to the Model.
 
 ** The debug mode
 
-To activate an deactivate the Pamhyr2 debug mode you can open the
-configuration window and type "Ctrl+G" or run Pamhyr2 with command
-line:
+To activate an deactivate the {{{pamhyr2}}} debug mode you can open
+the configuration window and type "Ctrl+G" or run {{{pamhyr2}}} with
+command line:
 #+begin_src shell
 ./Pamhyr2 debug
 #+end_src
@@ -1015,7 +1002,7 @@ data base file.
 
 #+NAME: debug-repl
 #+ATTR_LATEX: :width 14cm
-#+CAPTION: Pamhyr2 debug Python REPL
+#+CAPTION: {{{pamhyr2}}} debug Python REPL
 [[./images/python-debug-repl.png]]
 
 * Build the project
@@ -1028,7 +1015,7 @@ to build packages manually.
 If you need an hand made package, you can script available in
 {{{file(packages)}}} directory.
 
-*** GNU/Linux
+*** GNU/Linux {{{linux}}}
 
 On GNU/Linux building GNU/Linux packages is easy, you just need python
 in version 3.8 must be installed with venv and pyinstaller packages
@@ -1050,7 +1037,7 @@ cd packages
 ./linux.sh
 #+end_src
 
-*** Windows
+*** Windows {{{windows}}}
 
 To make the Windows packages you have two choice: If you use Windows
 you can use the script {{{file(packages/windows.bat)}}}, other else
@@ -1065,10 +1052,10 @@ winetricks installed.
 
 ** Setup the CI environment
 
-Pamhyr2 need a Linux ci-runner and a Windows ci-runner for building
+{{{pamhyr2}}} need a Linux ci-runner and a Windows ci-runner for building
 package. The windows ci-runner could run on a Wine environement.
 
-*** Linux
+*** Linux {{{linux}}}
 
 The Linux ci-runner need some software and dependencies in addtion of
 gitlab-ci.
@@ -1078,10 +1065,11 @@ gitlab-ci.
        emacs emacs-goodies-el                     \
        texlive-full                               \
        python3.8 python3.8-venv
+
   sudo python3 -m pip install pyinstaller
 #+end_src
 
-*** Windows (Wine)
+*** Windows (Wine) {{{windows}}}
 
 The ci-runner environment for Wine need at least wine version 8, let
 [[https://www.numetopia.fr/comment-installer-wine-sur-ubuntu-ou-linux-mint/][see who to add wine official depot to your linux distribution]].
@@ -1090,18 +1078,77 @@ The ci-runner environment for Wine need at least wine version 8, let
 sudo apt install wine-stable winetricks
 #+end_src
 
-In addition, the environment need windows version of:
- - [[https://www.python.org/ftp/python/3.8.10/python-3.8.10-amd64.exe][Python 3.8.10]]
- - Git
- - PowerShell
- - Gitlab-ci
+**** Setup environment
+
+Export Wine environment variable to set wine as 64 bits architecture
+and set the correct path for wine environment.
+
+#+begin_src shell
+  export WINARCH=win64
+  export WINEPREFIX=$PWD/my-wine-runner-prefix
+#+end_src
+
+Setup Wine environment to Windows 10 and install the minimal fonts
+with =winetricks=.
+
+#+begin_src shell
+  winetricks corefonts win10
+#+end_src
+
+**** Install dependencies
+
+First install 7zip with help of =winetricks=.
+
+#+begin_src shell
+  winetricks 7zip
+#+end_src
+
+In addition, install in the environment the Windows version of:
+ - [[https://www.python.org/ftp/python/3.8.10/python-3.8.10-amd64.exe][Python 3.8.10]] (ensure the python path is set and Pip is enable)
+ - [[https://git-scm.com/downloads][Git]]
+ - [[https://github.com/PowerShell/PowerShell/releases/download/v7.0.1/PowerShell-7.0.1-win-x64.msi][PowerShell]]
  - [[https://freefr.dl.sourceforge.net/project/nsis/NSIS%203/3.08/nsis-3.08-setup.exe][Nsis]]
 
+To run a Windows executable into wine environement, use =wine64= command:
+
+#+begin_src shell
+  wine64 <the-exe-file>
+#+end_src
+
 Now, we can install =pyinstaller= on this windows environment:
 #+begin_src shell
 wine python -m pip install pyinstaller
 #+end_src
 
+Now, we can download [[https://docs.gitlab.com/runner/install/windows.html][Gitlab-ci]] runner for Windows an put it in the
+current path.
+
+**** Setup runner
+
+You can configure the runner with command:
+
+#+begin_src shell
+  wine64 gitlab-runner-windows-amd64.exe register
+#+end_src
+
+**** Run the runner
+
+Create a new executable shell script =runner.sh= with following lines:
+
+#+begin_src shell
+  #! /bin/sh
+
+  export WINARCH=win64
+  export WINEPREFIX=$PWD/my-wine-runner-prefix
+
+  wine64 gitlab-runner-windows-amd64.exe run
+#+end_src
+
+Now you can run the runner with command =./runner.sh=.
+
+{{{bulb}}} You can run this command into a =screen= terminal, detach
+the terminal and disconnect from runner machine to keep runner alive.
+
 * Documentation files
 
 This document and the user documentation are org files. This text file
@@ -1284,23 +1331,23 @@ Some org-mode configuration used in documentations files are define in
 
 * How to contribute?
 
-Pamhyr2 is free software: you can redistribute it and/or modify it
-under the terms of the GNU General Public License[fn:license], either
-version 3 of the License, or any later version.
+{{{pamhyr2}}} is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License[fn:license],
+either version 3 of the License, or any later version.
 
 [fn:license] The GPLv3 web page:
 https://www.gnu.org/licenses/gpl-3.0.en.html
 
 ** Guidelines
 
-To contribute to Pamhyr2, we expect a minimum of respect between
+To contribute to {{{pamhyr2}}}, we expect a minimum of respect between
 contributors. We therefore ask you to respect the following rules
 regarding communication and contribution content:
 + No gender, racial, religious or social discrimination
 + No insults, personal attacks or potentially offensive remarks
-+ Pamhyr2 is free software, and intended to remain so, so take care
-  with the licensing of libraries and external content you want to add
-  to the project
++ {{{pamhyr2}}} is free software, and intended to remain so, so take
+  care with the licensing of libraries and external content you want
+  to add to the project
 + Humour or hidden easter eggs are welcome if they respect the
   previous rules
 
@@ -1311,11 +1358,12 @@ an issue on the project's gitlab page[fn:p2-gitlab], or you can create
 a merge request on the same page with the changes you have made to the
 code, translation or documentation.
 
-The Pamhyr2 copyright is owned by INRAE[fn:inrae], but we keep a
-record of each contributors. If you made a modification to pamhyr2
-software, please add your name at the end of {{{file(AUTHORS)}}} file
-and respect the Listing [[auth-format]] format. You can update this file
-information for following contribution.
+The {{{pamhyr2}}} copyright is owned by INRAE[fn:inrae], but we keep a
+record of each contributors. If you made a modification to
+{{{pamhyr2}}} software, please add your name at the end of
+{{{file(AUTHORS)}}} file and respect the Listing [[auth-format]]
+format. You can update this file information for following
+contribution.
 
 #+NAME: auth-format
 #+CAPTION: =AUTHORS= file format
@@ -1326,16 +1374,17 @@ information for following contribution.
 #+CAPTION: Current =AUTHORS= file
 #+INCLUDE: "../../AUTHORS" src text
 
-[fn:p2-gitlab] The Pamhyr2 Gitlab project page:
+[fn:p2-gitlab] The {{{pamhyr2}}} Gitlab project page:
 https://gitlab.irstea.fr/theophile.terraz/pamhyr
 [fn:inrae] The INRAE web site: https://www.inrae.fr/
 
 ** Translate
 
 You can improve or add translation for the project. To contribute to
-Pamhyr2 translate, you need to use Qt Linguist[fn:qt-linguist]. Open
-Qt-linguist and edit the translation ({{{file(.ts)}}}) file, finally,
-commit the new version of file and make a merge request.
+{{{pamhyr2}}} translate, you need to use Qt
+Linguist[fn:qt-linguist]. Open Qt-linguist and edit the translation
+({{{file(.ts)}}}) file, finally, commit the new version of file and
+make a merge request.
 
 If you want add a new language, edit the script
 {{{file(src/lang/create_ts.sh)}}} like Listing [[ts-it]]. Run the script
@@ -1344,7 +1393,7 @@ and open the new file with Qt-linguist, setup target language (Figure
 file and make a merge request.
 
 #+NAME: ts-it
-#+CAPTION: Example of modified {{{file(src/lang/create_ts.sh)}}} to add italian (it) translate for Pamhyr2
+#+CAPTION: Example of modified {{{file(src/lang/create_ts.sh)}}} to add italian (it) translate for {{{pamhyr2}}}
 #+begin_src shell
   ...
   LANG="fr it"
@@ -1362,7 +1411,7 @@ https://doc.qt.io/qt-5/qtlinguist-index.html (last access 2023-09-18)
 ** Code contribution
 
 If you are developper you can improve and/or add features to
-Pamhyr2. Please, follow the architecture described in section
+{{{pamhyr2}}}. Please, follow the architecture described in section
 [[Architecture]] as closely as possible. Keep the code simple, clear and
 efficient as possible. The master branch is reserved for the project
 maintainer; you can create a new branch or fork the project before the

doc/tools/PamhyrDoc.cls

@@ -163,3 +163,7 @@
 \SetWatermarkScale{3}
 \SetWatermarkFontSize{1cm}
 \SetWatermarkText{Work in progress}
+
+%% Icons
+
+\usepackage{fontawesome5}

doc/tools/macro.org

@@ -17,11 +17,15 @@
 # -*- coding: utf-8 -*-
 
 # Constant name
-#+MACRO: oldPamhyr     PAMHyR
-#+MACRO: Pamhyr        Pamhyr2
-#+MACRO: Mage          Mage
-#+MACRO: Rubarbe       RubarBE
-#+MACRO: Inrae         INRAE
+#+MACRO: pamhyr        \textsc{PAMHyR}
+#+MACRO: pamhyr2       \textsc{Pamhyr2}
+#+MACRO: mage          \textsc{Mage}
+#+MACRO: mage7         \textsc{Mage7}
+#+MACRO: mage8         \textsc{Mage8}
+#+MACRO: rubarbe       \textsc{RubarBE}
+#+MACRO: adists        \textsc{AdisTS}
+#+MACRO: mascaret      \textsc{Mascaret}
+#+MACRO: inrae         INRAE
 #+MACRO: latex         \LaTeX
 
 # Information
@@ -35,6 +39,16 @@
 #+MACRO: cite          [cite:$1]
 #+MACRO: biblio        \bibliography{documentation}
 
+# Icons
+#+MACRO: bulb \faIcon{lightbulb}
+#+MACRO: OK  \faIcon{check}
+
+#+MACRO: linux  \faIcon{linux}
+#+MACRO: windows  \faIcon{windows}
+
+#+MACRO: python  \faIcon{python}
+#+MACRO: java  \faIcon{java}
+
 # Wrapper
 #+NAME: attr_wrap
 #+HEADER: :var width="\\textwidth"