diff --git a/doc/dev/documentation.org b/doc/dev/documentation.org index f7285945ad04561cbb8e81531466006c4ca30640..7e96edc4b69c232afddced30dfe73740e24d9a70 100644 --- a/doc/dev/documentation.org +++ b/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 diff --git a/doc/tools/PamhyrDoc.cls b/doc/tools/PamhyrDoc.cls index a58837204ea56de17d7b82ab38738f00fdb1fcad..431f89427988f89fd8f41a08869ea506c259604a 100644 --- a/doc/tools/PamhyrDoc.cls +++ b/doc/tools/PamhyrDoc.cls @@ -163,3 +163,7 @@ \SetWatermarkScale{3} \SetWatermarkFontSize{1cm} \SetWatermarkText{Work in progress} + +%% Icons + +\usepackage{fontawesome5} diff --git a/doc/tools/macro.org b/doc/tools/macro.org index 9c59153f3fe0f75d19005df179eafda887f4eae7..87cf15c895ee29882ad9c1a4451b47651e9e2bdb 100644 --- a/doc/tools/macro.org +++ b/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"