mirror of https://gitlab.com/pamhyr/pamhyr2
Merge branch 'doc' into refactoring.
Pierre-Antoine Rouby
commit
c12c06a604
|
|
@ -0,0 +1,10 @@
|
||||||
|
#! /bin/sh
|
||||||
|
|
||||||
|
# Build the PDF
|
||||||
|
|
||||||
|
emacs -Q -q -nw --batch \
|
||||||
|
--eval "(require 'org)" \
|
||||||
|
--eval "(require 'ox-latex)" \
|
||||||
|
--eval "(load-file \"../tools/setup.el\")" \
|
||||||
|
--file ./documentation.org \
|
||||||
|
-f org-latex-export-to-pdf
|
||||||
|
|
@ -0,0 +1 @@
|
||||||
|
../tools/ref.bib
|
||||||
|
|
@ -0,0 +1,551 @@
|
||||||
|
# documentation.org -- Pamhyr developers documentation
|
||||||
|
# Copyright (C) 2023 INRAE
|
||||||
|
#
|
||||||
|
# This program is free software: you can redistribute it and/or modify
|
||||||
|
# it under the terms of the GNU General Public License as published by
|
||||||
|
# the Free Software Foundation, either version 3 of the License, or
|
||||||
|
# (at your option) any later version.
|
||||||
|
#
|
||||||
|
# This program is distributed in the hope that it will be useful,
|
||||||
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||||
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||||
|
# GNU General Public License for more details.
|
||||||
|
#
|
||||||
|
# You should have received a copy of the GNU General Public License
|
||||||
|
# along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||||
|
|
||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
|
||||||
|
#+STARTUP: indent
|
||||||
|
|
||||||
|
#+INCLUDE: ../tools/macro.org
|
||||||
|
#+INCLUDE: ../tools/latex.org
|
||||||
|
|
||||||
|
#+TITLE: Developers documentation
|
||||||
|
#+SUBTITLE: Version: {{{version}}}
|
||||||
|
#+AUTHOR: {{{INRAE}}}
|
||||||
|
|
||||||
|
#+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
|
||||||
|
debugging. It also describes the procedures for creating packages and
|
||||||
|
the configurations required to set up the gitlab runners. Finally,
|
||||||
|
this document explains how documentation is written and modified, and
|
||||||
|
how to contribute to the project by modifying, improving or adding
|
||||||
|
documentation, translations or code.
|
||||||
|
#+END_abstract
|
||||||
|
|
||||||
|
* Introduction
|
||||||
|
|
||||||
|
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
|
||||||
|
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],
|
||||||
|
let see section [[Documentation files]]. Finally, to see the contribution
|
||||||
|
rules, see the section [[How to contribute?]].
|
||||||
|
|
||||||
|
[fn:qt-arch] Qt Model/View documentation:
|
||||||
|
https://doc.qt.io/qt-5/model-view-programming.html (last access
|
||||||
|
2023-09-15)
|
||||||
|
[fn:org] The org-mode website: https://orgmode.org/ (last access
|
||||||
|
2023-09-15)
|
||||||
|
|
||||||
|
* TODO Architecture
|
||||||
|
|
||||||
|
Pamhyr2 architecture is based on Qt Model/View programming[fn:qt-mv] architecture.
|
||||||
|
|
||||||
|
#+name: graph-pipeline
|
||||||
|
#+header: :results drawer
|
||||||
|
#+header: :exports results
|
||||||
|
#+header: :post attr_wrap(width="12cm", data=*this*, name="graph-pipeline", caption="Pamhyr2 solver execution pipeline architecture scheme", float="t")
|
||||||
|
#+begin_src dot :file "images/graph-pipeline.png" :cache no
|
||||||
|
digraph {
|
||||||
|
node[colorscheme=set19,shape=box,style="filled",fillcolor=9];
|
||||||
|
|
||||||
|
subgraph cluster0 {
|
||||||
|
label="Pamhyr2"
|
||||||
|
config[label="Config",fillcolor=5];
|
||||||
|
model[label="Model",fillcolor=2];
|
||||||
|
obj[label="Solver",fillcolor=6];
|
||||||
|
results[label="Results",fillcolor=2];
|
||||||
|
view[label="View",fillcolor=1];
|
||||||
|
|
||||||
|
results -> model[style="dotted"];
|
||||||
|
results -> obj[style="dotted"];
|
||||||
|
}
|
||||||
|
|
||||||
|
config -> obj[label=""];
|
||||||
|
obj -> model;
|
||||||
|
|
||||||
|
subgraph cluster1{
|
||||||
|
label="System";
|
||||||
|
in[label="Solver input files",shape=note];
|
||||||
|
out[label="Solver output files",shape=note];
|
||||||
|
bin[label="Solver binary",shape=note];
|
||||||
|
}
|
||||||
|
|
||||||
|
obj -> in[label="Write"];
|
||||||
|
bin -> in[label="Read"];
|
||||||
|
obj -> bin[label="Execute"];
|
||||||
|
bin -> out[label="Write"];
|
||||||
|
obj -> results[label="Create"];
|
||||||
|
results -> out[label="Read"];
|
||||||
|
view -> model;
|
||||||
|
view -> results;
|
||||||
|
}
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
#+name: graph-architecture
|
||||||
|
#+header: :results drawer
|
||||||
|
#+header: :exports results
|
||||||
|
#+header: :post attr_wrap(width="7cm", data=*this*, name="graph-architecture", caption="Pamhyr2 Model/View architecture scheme (inspired by Qt Model/View architecture [[https://doc.qt.io/qt-5/model-view-programming.html]])", float="t")
|
||||||
|
#+begin_src dot :file "images/graph-architecture.png" :cache no
|
||||||
|
digraph {
|
||||||
|
node[colorscheme=set19,shape=box,style="filled",fillcolor=white];
|
||||||
|
|
||||||
|
save[label="Pamhyr save",fillcolor="9",shape=note];
|
||||||
|
model[label="Model",fillcolor="2"];
|
||||||
|
view[label="View",fillcolor="1"];
|
||||||
|
delegate[label="Delegate",fillcolor="3"];
|
||||||
|
undocommand[label="UndoCommand",fillcolor="4"];
|
||||||
|
user[label="User",shape=ellipse];
|
||||||
|
|
||||||
|
model -> save[label="Save"];
|
||||||
|
save -> model[label="Load"];
|
||||||
|
|
||||||
|
model -> view[label="Rendering"];
|
||||||
|
view -> delegate[label="Rendering"];
|
||||||
|
delegate -> undocommand[label="Create"];
|
||||||
|
undocommand -> model[label="Modify"]
|
||||||
|
|
||||||
|
view -> user[label="Vizualize"];
|
||||||
|
user -> delegate[label="Modify"];
|
||||||
|
}
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
#+name: graph-model
|
||||||
|
#+header: :results drawer
|
||||||
|
#+header: :exports results
|
||||||
|
#+header: :post attr_wrap(width="16cm", data=*this*, name="graph-model", caption="Pamhyr2 Model architecture scheme", float="t")
|
||||||
|
#+begin_src dot :file "images/graph-model.png" :cache no
|
||||||
|
digraph {
|
||||||
|
node[colorscheme=set19,shape=box,style="filled",fillcolor="2"];
|
||||||
|
|
||||||
|
study[label="Study"];
|
||||||
|
river[label="River"];
|
||||||
|
|
||||||
|
subgraph cluster00 {
|
||||||
|
label="Network"
|
||||||
|
rnode[label="RiverNode"];
|
||||||
|
redge[label="RiverReach"];
|
||||||
|
}
|
||||||
|
|
||||||
|
frictionlist[label="FrictionList"];
|
||||||
|
|
||||||
|
subgraph cluster01 {
|
||||||
|
label="Stricklers";
|
||||||
|
stricklers[label="Stricklers"];
|
||||||
|
stricklerslist[label="StricklersList"];
|
||||||
|
}
|
||||||
|
subgraph cluster02 {
|
||||||
|
label="BoundaryCondition";
|
||||||
|
boundaryconditionlist[label="BoundaryConditionList"];
|
||||||
|
boundarycondition[label="BoundaryCondition"];
|
||||||
|
}
|
||||||
|
subgraph cluster03 {
|
||||||
|
label="LateralContribution";
|
||||||
|
lateralcontributionlist[label="LateralContributionList"];
|
||||||
|
lateralcontribution[label="LateralContribution"];
|
||||||
|
}
|
||||||
|
subgraph cluster04 {
|
||||||
|
label="InitialConditions";
|
||||||
|
initialconditionsdict[label="InitialConditionsDict"];
|
||||||
|
initialconditions[label="InitialConditions"];
|
||||||
|
}
|
||||||
|
|
||||||
|
solverparameterslist[label="SolverParametersList"];
|
||||||
|
|
||||||
|
subgraph cluster05 {
|
||||||
|
label="Sediment";
|
||||||
|
sedimentlayerlist[label="SedimentLayerList"];
|
||||||
|
sedimentlayer[label="SedimentLayer"];
|
||||||
|
layer[label="Layer"];
|
||||||
|
}
|
||||||
|
|
||||||
|
subgraph cluster06 {
|
||||||
|
label="Greometry"
|
||||||
|
georeach[label="Reach"];
|
||||||
|
geocrosssection[label="Cross-section"];
|
||||||
|
geopoint[label="Point"];
|
||||||
|
}
|
||||||
|
|
||||||
|
study -> river;
|
||||||
|
river -> rnode;
|
||||||
|
river -> redge;
|
||||||
|
redge -> rnode;
|
||||||
|
river -> boundaryconditionlist -> boundarycondition -> rnode;
|
||||||
|
river -> lateralcontributionlist -> lateralcontribution -> redge;
|
||||||
|
river -> initialconditionsdict -> initialconditions;
|
||||||
|
initialconditions -> redge;
|
||||||
|
river -> stricklerslist -> stricklers;
|
||||||
|
river -> solverparameterslist;
|
||||||
|
river -> sedimentlayerlist -> sedimentlayer -> layer;
|
||||||
|
redge -> frictionlist -> stricklers;
|
||||||
|
redge -> georeach -> geocrosssection -> geopoint;
|
||||||
|
geocrosssection -> sedimentlayer;
|
||||||
|
geopoint -> sedimentlayer;
|
||||||
|
|
||||||
|
}
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
[fn:qt-mv] The Qt Model/View documentation web page:
|
||||||
|
https://doc.qt.io/qt-5/model-view-programming.html
|
||||||
|
|
||||||
|
** TODO Model
|
||||||
|
** TODO View
|
||||||
|
*** TODO UI file
|
||||||
|
*** TODO Window class
|
||||||
|
** TODO UndoCommand
|
||||||
|
** TODO Table
|
||||||
|
** TODO Plot
|
||||||
|
** TODO Solver
|
||||||
|
** TODO Unit tests
|
||||||
|
** TODO The debug mode
|
||||||
|
* TODO Build the project
|
||||||
|
|
||||||
|
The project uses gitlab-ci runners to build packages, but it is possible
|
||||||
|
to build packages manually.
|
||||||
|
|
||||||
|
** Building packages
|
||||||
|
|
||||||
|
If you need an hand made package, you can script available in
|
||||||
|
{{{file(packages)}}} directory.
|
||||||
|
|
||||||
|
*** GNU/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
|
||||||
|
(see Listing [[linux-env-deb]] for Debian and derived system). Finally,
|
||||||
|
run the {{{file(linux.sh)}}} script (see Listing [[linux-pkg]]).
|
||||||
|
|
||||||
|
#+NAME: linux-env-deb
|
||||||
|
#+CAPTION: Install environment on GNU/Linux
|
||||||
|
#+begin_src shell
|
||||||
|
sudo apt install python3.8
|
||||||
|
python3 -m pip install venv
|
||||||
|
python3 -m pip install pyinstaller
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
#+NAME: linux-pkg
|
||||||
|
#+CAPTION: Build GNU/Linux package
|
||||||
|
#+begin_src shell
|
||||||
|
cd packages
|
||||||
|
./linux.sh
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
*** 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
|
||||||
|
you can use the script {{{file(packages/wine.sh)}}}. Each script need
|
||||||
|
a specific software environment.
|
||||||
|
|
||||||
|
On windows, you needs python on version 3.8, pyinstaller and
|
||||||
|
NSIS[fn:nsis] installed. On GNU/Linux you need wget, wine and
|
||||||
|
winetricks installed.
|
||||||
|
|
||||||
|
[fn:nsis] The NSIS web site: https://sourceforge.net/projects/nsis/
|
||||||
|
|
||||||
|
** TODO Setup the CI environment
|
||||||
|
* Documentation files
|
||||||
|
|
||||||
|
This document and the user documentation are org files. This text file
|
||||||
|
format is formatted so that it can be exported in different formats:
|
||||||
|
PDF (with latex), ODT, HTML, etc. It was originally designed for the
|
||||||
|
GNUEmacs[fn:emacs] text editor, but can be edited with any text editor. Here we
|
||||||
|
take a look at the different features used in these documents.
|
||||||
|
|
||||||
|
[fn:org] The org-mode website: https://orgmode.org/ (last access
|
||||||
|
2023-09-15)
|
||||||
|
[fn:emacs] The GNUEmacs project website: https://gnu.org/s/emacs/
|
||||||
|
(last access 2023-09-15)
|
||||||
|
|
||||||
|
** Org-mode
|
||||||
|
*** Document structure
|
||||||
|
|
||||||
|
Org uses the =*= character to define a new document section. To add a
|
||||||
|
sub-section, you can add an additional =*= to the current section[fn::
|
||||||
|
See document structure documentation:
|
||||||
|
https://orgmode.org/org.html#Headlines (last access 2023-09-15)].
|
||||||
|
|
||||||
|
#+BEGIN_EXAMPLE
|
||||||
|
* Top level headline
|
||||||
|
** Second level
|
||||||
|
*** Third level
|
||||||
|
some text
|
||||||
|
*** Third level
|
||||||
|
more text
|
||||||
|
* Another top level headline
|
||||||
|
#+END_EXAMPLE
|
||||||
|
|
||||||
|
*** Format
|
||||||
|
|
||||||
|
Org-mode is a markup file, using markup in the text to modify the
|
||||||
|
appearance of a portion of text[fn:: See markup documentation:
|
||||||
|
https://orgmode.org/org.html#Emphasis-and-Monospace (last access
|
||||||
|
2023-09-15)].
|
||||||
|
|
||||||
|
| Markup | Results |
|
||||||
|
|--------------------+------------------|
|
||||||
|
| =*Bolt*= | *Bolt* |
|
||||||
|
| =/Italic/= | /Italic/ |
|
||||||
|
| =_underline_= | _underline_ |
|
||||||
|
| ==verbatim== | =verbatim= |
|
||||||
|
| =~code~= | ~code~ |
|
||||||
|
| =+strike-through+= | +strike-through+ |
|
||||||
|
|
||||||
|
*** Source code blocks
|
||||||
|
|
||||||
|
You can add some code blocks[fn:: See org-mode documentation for
|
||||||
|
source code: https://orgmode.org/org.html#Working-with-Source-Code
|
||||||
|
(last access 2023-09-15)] in the document.
|
||||||
|
|
||||||
|
Here is an example for python source code:
|
||||||
|
#+BEGIN_EXAMPLE
|
||||||
|
#+CAPTION: Get os type name in Python code
|
||||||
|
#+begin_src python
|
||||||
|
import os
|
||||||
|
|
||||||
|
print(f"Document build on system: {os.name}")
|
||||||
|
#+end_src
|
||||||
|
#+END_EXAMPLE
|
||||||
|
|
||||||
|
If you use GNUEmacs, it is also possible to run the code inside a
|
||||||
|
block and export (or not) the reuslts in the document.
|
||||||
|
|
||||||
|
#+OPTIONS: float:nil
|
||||||
|
#+CAPTION: Get os type name in Python code
|
||||||
|
#+begin_src python :python python3 :results output :exports both :noweb yes
|
||||||
|
import os
|
||||||
|
|
||||||
|
print(f"Document build on system: {os.name}")
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
#+RESULTS:
|
||||||
|
: Document build on system: posix
|
||||||
|
|
||||||
|
*** LaTeX
|
||||||
|
|
||||||
|
If we export the file to PDF, org-mode use {{{latex}}}. So we can add
|
||||||
|
some piece of {{{latex}}} into the document[fn:: See {{{latex}}} part
|
||||||
|
in documentation: https://orgmode.org/org.html#Embedded-LaTeX (last
|
||||||
|
access 2023-09-15)]. For exemple, we can add math formula like
|
||||||
|
=$E=mc^2$= ($E=mc^2$) or =\[E=mc^2\]=:
|
||||||
|
|
||||||
|
\[E=mc^2\]
|
||||||
|
|
||||||
|
But we can also add every type of {{{latex}}}:
|
||||||
|
|
||||||
|
#+BEGIN_EXAMPLE
|
||||||
|
# Add latex in line
|
||||||
|
#+LATEX: <my line of latex>
|
||||||
|
|
||||||
|
# Add multiple line of LaTeX
|
||||||
|
#+BEGIN_EXPORT latex
|
||||||
|
<my latex here>
|
||||||
|
#+END_EXPORT
|
||||||
|
#+END_EXAMPLE
|
||||||
|
|
||||||
|
It is also possible to add specific {{{latex}}} file header with
|
||||||
|
=#+LATEX_HEADER=. In this document we use the file
|
||||||
|
{{{file(doc/tools/latex.org)}}} for all {{{latex}}} headers.
|
||||||
|
|
||||||
|
*** Macro
|
||||||
|
|
||||||
|
In this document, we use a few macros[fn:: See marcos documentation
|
||||||
|
https://orgmode.org/org.html#Macro-Replacement (last access
|
||||||
|
2023-09-15)] to simplify writing. They allow you to define sequences
|
||||||
|
of text to be replaced, so that the macro name is replaced by its
|
||||||
|
value. They are defined in the {{{file(doc/tools/macro.org)}}}
|
||||||
|
file. Once defined, they can be used in the document as follows:
|
||||||
|
={{{<macro-name>}}}=. You can also have macros with arguments, in this
|
||||||
|
case: ={{{<macro-name>(arg1,...)}}}=. Les macros peuvent aussi
|
||||||
|
utiliser du code emacs-lisp.
|
||||||
|
|
||||||
|
#+BEGIN_EXAMPLE
|
||||||
|
# Exemple of macro définition
|
||||||
|
|
||||||
|
#+MACRO: toto tata
|
||||||
|
#+MACRO: add \(($1 + $2)\)
|
||||||
|
#+MACRO: emacs-version (eval (nth 2 (split-string (emacs-version))))
|
||||||
|
#+END_EXAMPLE
|
||||||
|
|
||||||
|
#+MACRO: toto tata
|
||||||
|
#+MACRO: add \(($1 + $2)\)
|
||||||
|
#+MACRO: emacs-version (eval (nth 2 (split-string (emacs-version))))
|
||||||
|
|
||||||
|
Macro apply:
|
||||||
|
- Marco ={{{toto}}}=: {{{toto}}}
|
||||||
|
- Marco ={{{add(x,y)}}}=: {{{add(x,y)}}}
|
||||||
|
- Marco ={{{emacs-version}}}=: {{{emacs-version}}}
|
||||||
|
|
||||||
|
*** Footnotes
|
||||||
|
|
||||||
|
Footnote in org-mode is define with marker =[fn:...]=[fn:: Create
|
||||||
|
footnotes in org-mode documentation
|
||||||
|
https://orgmode.org/org.html#Creating-Footnotes (last access
|
||||||
|
2023-09-15)]:
|
||||||
|
#+BEGIN_EXAMPLE
|
||||||
|
The Org website[fn:1] now looks a lot better than it used to.
|
||||||
|
...
|
||||||
|
[fn:1] The link is: https://orgmode.org
|
||||||
|
#+END_EXAMPLE
|
||||||
|
or:
|
||||||
|
#+BEGIN_EXAMPLE
|
||||||
|
The Org website[fn:: The link is: https://orgmode.org] now looks
|
||||||
|
a lot better than it used to.
|
||||||
|
...
|
||||||
|
#+END_EXAMPLE
|
||||||
|
|
||||||
|
*** References
|
||||||
|
|
||||||
|
The references use the {{{latex}}} bibtex tools. The bib file is in
|
||||||
|
{{{file(/doc/tools/ref.bib)}}} and use for developers and user
|
||||||
|
documentation. In document, use ={{{cite(<name>)}}}= to cite a paper.
|
||||||
|
|
||||||
|
** Export
|
||||||
|
|
||||||
|
To export the files, a {{{file(build.sh)}}} script is available in the org
|
||||||
|
files directories. On GNU/Linux system you can build the documentation
|
||||||
|
PDF file with the command =./build.sh=. Texlive package must be
|
||||||
|
installed, you can install only needed packages or all texlive
|
||||||
|
packages, for example on Debian (and some derived system) use command
|
||||||
|
Listing [[texlive-install]].
|
||||||
|
|
||||||
|
#+NAME: texlive-install
|
||||||
|
#+CAPTION: Installation command for texlive full on Debian system
|
||||||
|
#+begin_src shell
|
||||||
|
sudo apt install texlive-full
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
Some org-mode configuration used in documentations files are define in
|
||||||
|
=/doc/tools/=:
|
||||||
|
- {{{file(PamhyrDoc.cls)}}}: The {{{latex}}} document class
|
||||||
|
- {{{file(macro.org)}}}: Available macro
|
||||||
|
- {{{file(latex.org)}}}: {{{latex}}} configutation for documentations
|
||||||
|
files
|
||||||
|
- {{{file(setup.el)}}}: GNUEmacs configuration to build documentations
|
||||||
|
- {{{file(ref.bib)}}}: Bibtex files for documentations files
|
||||||
|
|
||||||
|
* 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.
|
||||||
|
|
||||||
|
[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
|
||||||
|
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
|
||||||
|
+ Humour or hidden easter eggs are welcome if they respect the
|
||||||
|
previous rules
|
||||||
|
|
||||||
|
** Make a contribution
|
||||||
|
|
||||||
|
There are several ways to contribute: you can report a bug by creating
|
||||||
|
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.
|
||||||
|
|
||||||
|
#+NAME: auth-format
|
||||||
|
#+CAPTION: =AUTHORS= file format
|
||||||
|
#+begin_src text
|
||||||
|
<first name> <last name> [(optional) email], <organisation>, <years>
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
#+CAPTION: Current =AUTHORS= file
|
||||||
|
#+INCLUDE: "../../AUTHORS" src text
|
||||||
|
|
||||||
|
[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 edite 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
|
||||||
|
and open the new file with Qt-linguist, setup target language (Figure
|
||||||
|
[[qt-linguist-setup]]) and complete translation. Finally, commit the new
|
||||||
|
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
|
||||||
|
#+begin_src shell
|
||||||
|
...
|
||||||
|
LANG="fr it"
|
||||||
|
...
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
#+NAME: qt-linguist-setup
|
||||||
|
#+ATTR_HTML: :width 8cm
|
||||||
|
#+ATTR_LATEX: :width 8cm
|
||||||
|
#+CAPTION: Qt linguist lang setup example with italian.
|
||||||
|
[[../images/Qt-linguist-setup-lang.png]]
|
||||||
|
|
||||||
|
[fn:qt-linguist] The Qt linguist documentation web page:
|
||||||
|
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
|
||||||
|
[[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
|
||||||
|
request.
|
||||||
|
|
||||||
|
|
||||||
|
{{{biblio}}}
|
||||||
Binary file not shown.
|
After Width: | Height: | Size: 61 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
|
|
@ -0,0 +1,163 @@
|
||||||
|
\ProvidesClass{Pamhyr}[Pamhyr class]
|
||||||
|
\NeedsTeXFormat{LaTeX2e}
|
||||||
|
\ProcessOptions\relax
|
||||||
|
\LoadClass[11pt,a4paper]{article}
|
||||||
|
|
||||||
|
\usepackage[hmargin=2cm, vmargin=3cm]{geometry}
|
||||||
|
\usepackage[british,UKenglish,USenglish,english,american]{babel}
|
||||||
|
\usepackage[T1]{fontenc}
|
||||||
|
\usepackage{times}
|
||||||
|
\usepackage[usenames,dvipsnames]{xcolor}
|
||||||
|
\usepackage[absolute]{textpos}
|
||||||
|
\usepackage{titlesec}
|
||||||
|
\usepackage{amssymb}
|
||||||
|
\usepackage{tcolorbox}
|
||||||
|
|
||||||
|
\usepackage{enumitem}
|
||||||
|
\setlist[enumerate]{itemsep=-0.5em}
|
||||||
|
\setlist[itemize]{itemsep=-0.5em}
|
||||||
|
|
||||||
|
%%
|
||||||
|
%% Bibtex
|
||||||
|
%%
|
||||||
|
|
||||||
|
\bibliographystyle{plain}
|
||||||
|
|
||||||
|
%%
|
||||||
|
%% Colors
|
||||||
|
%%
|
||||||
|
|
||||||
|
\definecolor{primary}{HTML}{212121}
|
||||||
|
\definecolor{lightheadings}{HTML}{5c5c5c}
|
||||||
|
\definecolor{headings}{HTML}{212121}
|
||||||
|
\definecolor{links}{HTML}{e12121}
|
||||||
|
|
||||||
|
%%
|
||||||
|
%% Title
|
||||||
|
%%
|
||||||
|
|
||||||
|
\setlength{\columnsep}{20pt}
|
||||||
|
\setlength{\parskip}{0pt} %% inter paragraph space
|
||||||
|
|
||||||
|
\renewcommand{\maketitle}{
|
||||||
|
{
|
||||||
|
\centering
|
||||||
|
{
|
||||||
|
\fontsize{35}{40}
|
||||||
|
\selectfont
|
||||||
|
\scshape
|
||||||
|
Pamhyr2 \\
|
||||||
|
\medskip
|
||||||
|
}
|
||||||
|
{
|
||||||
|
%\centering
|
||||||
|
\scshape
|
||||||
|
\fontsize{20pt}{24pt}
|
||||||
|
\selectfont
|
||||||
|
A graphical user interface for 1D hydro-sedimentary modelling
|
||||||
|
of rivers \\
|
||||||
|
\medskip
|
||||||
|
}
|
||||||
|
\rule{3cm}{0.4pt}\\
|
||||||
|
\vspace{0.3cm}
|
||||||
|
{
|
||||||
|
%\centering
|
||||||
|
\scshape
|
||||||
|
\fontsize{26pt}{24pt}
|
||||||
|
\selectfont
|
||||||
|
\@title \\
|
||||||
|
Document licence: GPLv3 \\
|
||||||
|
\medskip
|
||||||
|
\includegraphics[width=3cm]{../images/GPLv3_Logo.png} \\
|
||||||
|
\medskip
|
||||||
|
\fontsize{14pt}{16pt}
|
||||||
|
\selectfont
|
||||||
|
© \@author \\
|
||||||
|
\medskip
|
||||||
|
}
|
||||||
|
{
|
||||||
|
%\centering
|
||||||
|
%\scshape
|
||||||
|
\fontsize{12pt}{14pt}
|
||||||
|
\selectfont
|
||||||
|
\@date
|
||||||
|
%\medskip
|
||||||
|
}\\
|
||||||
|
\vspace{0.3cm}
|
||||||
|
\rule{3cm}{0.4pt}\\
|
||||||
|
\vspace{0.3cm}
|
||||||
|
{
|
||||||
|
\begin{minipage}[h]{0.24\textwidth}
|
||||||
|
\includegraphics[width=4cm]{../../src/View/ui/ressources/Logo-INRAE.png}
|
||||||
|
\end{minipage}
|
||||||
|
\begin{minipage}[h]{0.24\textwidth}
|
||||||
|
\includegraphics[width=4cm]{../images/riverly.png}
|
||||||
|
\end{minipage}
|
||||||
|
}\\
|
||||||
|
\vspace{0.3cm}
|
||||||
|
%%\rule{\textwidth}{0.4pt}
|
||||||
|
%%\newpage
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
%%
|
||||||
|
%% Texttt
|
||||||
|
%%
|
||||||
|
|
||||||
|
\usepackage[htt]{hyphenat} % Make texttt split at end of line
|
||||||
|
|
||||||
|
%%
|
||||||
|
%% Verbatim
|
||||||
|
%%
|
||||||
|
|
||||||
|
\AtBeginEnvironment{verbatim}{\footnotesize}
|
||||||
|
|
||||||
|
%% Add box arrond of verbatim
|
||||||
|
\BeforeBeginEnvironment{verbatim}{\begin{tcolorbox}[boxsep=0pt, left=0.1cm, right=0.1cm, arc=0pt, boxrule=0.5pt, colback=white]}%
|
||||||
|
\AfterEndEnvironment{verbatim}{\end{tcolorbox}}%
|
||||||
|
|
||||||
|
\makeatletter
|
||||||
|
\AtBeginEnvironment{verbatim}{\dontdofcolorbox}
|
||||||
|
|
||||||
|
\def\dontdofcolorbox{\renewcommand\fcolorbox[4][]{##4}}
|
||||||
|
\makeatother
|
||||||
|
|
||||||
|
%%
|
||||||
|
%% Source code blocks
|
||||||
|
%%
|
||||||
|
|
||||||
|
%% Use minted
|
||||||
|
\usepackage{minted}
|
||||||
|
\usemintedstyle{tango}
|
||||||
|
\setminted[c]{fontsize=\footnotesize,encoding=utf8,linenos}
|
||||||
|
\setminted[c++]{breaklines,fontsize=\footnotesize,encoding=utf8,linenos}
|
||||||
|
\setminted[python]{breaklines,fontsize=\footnotesize,encoding=utf8,linenos}
|
||||||
|
\setminted[shell]{breaklines,fontsize=\footnotesize,encoding=utf8}
|
||||||
|
\setminted[scheme]{breaklines,fontsize=\footnotesize,encoding=utf8}
|
||||||
|
\setminted[commun-lisp]{breaklines,fontsize=\footnotesize,encoding=utf8}
|
||||||
|
\setminted[text]{breaklines,fontsize=\footnotesize,encoding=utf8}
|
||||||
|
\setminted[llvm]{breaklines,fontsize=\footnotesize,encoding=utf8}
|
||||||
|
|
||||||
|
%% Add box arrond of minted
|
||||||
|
\BeforeBeginEnvironment{minted}{\begin{tcolorbox}[boxsep=0pt, left=0.1cm, right=0.1cm, arc=0pt, boxrule=0.5pt, colback=white]}%
|
||||||
|
\AfterEndEnvironment{minted}{\end{tcolorbox}}%
|
||||||
|
|
||||||
|
\makeatletter
|
||||||
|
\AtBeginEnvironment{minted}{\dontdofcolorbox}
|
||||||
|
|
||||||
|
\def\dontdofcolorbox{\renewcommand\fcolorbox[4][]{##4}}
|
||||||
|
\makeatother
|
||||||
|
|
||||||
|
|
||||||
|
%%
|
||||||
|
%% Water mark
|
||||||
|
%%
|
||||||
|
|
||||||
|
%% FIXME: Delete me for the first realease
|
||||||
|
\usepackage{draftwatermark}
|
||||||
|
\SetWatermarkLightness{0.8}
|
||||||
|
\SetWatermarkAngle{25}
|
||||||
|
\SetWatermarkScale{3}
|
||||||
|
\SetWatermarkFontSize{1cm}
|
||||||
|
\SetWatermarkText{Work in progress}
|
||||||
|
|
@ -0,0 +1,19 @@
|
||||||
|
# latex.org -- Pamhyr documentation latex config
|
||||||
|
# Copyright (C) 2023 INRAE
|
||||||
|
#
|
||||||
|
# This program is free software: you can redistribute it and/or modify
|
||||||
|
# it under the terms of the GNU General Public License as published by
|
||||||
|
# the Free Software Foundation, either version 3 of the License, or
|
||||||
|
# (at your option) any later version.
|
||||||
|
#
|
||||||
|
# This program is distributed in the hope that it will be useful,
|
||||||
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||||
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||||
|
# GNU General Public License for more details.
|
||||||
|
#
|
||||||
|
# You should have received a copy of the GNU General Public License
|
||||||
|
# along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||||
|
|
||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
|
||||||
|
#+LaTeX_CLASS: PamhyrDoc
|
||||||
|
|
@ -0,0 +1,51 @@
|
||||||
|
# macro.org -- Pamhyr documentation macro
|
||||||
|
# Copyright (C) 2023 INRAE
|
||||||
|
#
|
||||||
|
# This program is free software: you can redistribute it and/or modify
|
||||||
|
# it under the terms of the GNU General Public License as published by
|
||||||
|
# the Free Software Foundation, either version 3 of the License, or
|
||||||
|
# (at your option) any later version.
|
||||||
|
#
|
||||||
|
# This program is distributed in the hope that it will be useful,
|
||||||
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||||
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||||
|
# GNU General Public License for more details.
|
||||||
|
#
|
||||||
|
# You should have received a copy of the GNU General Public License
|
||||||
|
# along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||||
|
|
||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
|
||||||
|
# Constant name
|
||||||
|
#+MACRO: oldPamhyr PAMHyR
|
||||||
|
#+MACRO: Pamhyr Pamhyr2
|
||||||
|
#+MACRO: Mage Mage
|
||||||
|
#+MACRO: Rubarbe RubarBE
|
||||||
|
#+MACRO: Inrae INRAE
|
||||||
|
#+MACRO: latex \LaTeX
|
||||||
|
|
||||||
|
# Information
|
||||||
|
#+MACRO: version (eval (pamhyr-version))
|
||||||
|
#+MACRO: current-file (eval (pamhyr-current-file))
|
||||||
|
|
||||||
|
# Special format
|
||||||
|
#+MACRO: file =$1=
|
||||||
|
|
||||||
|
# Biblio
|
||||||
|
#+MACRO: cite [cite:$1]
|
||||||
|
#+MACRO: biblio \bibliography{documentation}
|
||||||
|
|
||||||
|
# Wrapper
|
||||||
|
#+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
|
||||||
|
|
@ -0,0 +1,66 @@
|
||||||
|
(require 'org)
|
||||||
|
(require 'subr-x)
|
||||||
|
|
||||||
|
;; LaTeX config
|
||||||
|
|
||||||
|
(add-to-list
|
||||||
|
'org-latex-classes
|
||||||
|
'("PamhyrDoc"
|
||||||
|
"\\documentclass{../tools/PamhyrDoc}"
|
||||||
|
("\\section{%s}" . "\\section*{%s}")
|
||||||
|
("\\subsection{%s}" . "\\subsection*{%s}")
|
||||||
|
("\\subsubsection{%s}" . "\\subsubsection*{%s}")
|
||||||
|
("\\paragraph{%s}" . "\\paragraph*{%s}")
|
||||||
|
("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
|
||||||
|
|
||||||
|
(setq org-confirm-babel-evaluate nil)
|
||||||
|
(setq org-latex-caption-above nil)
|
||||||
|
|
||||||
|
(org-babel-do-load-languages
|
||||||
|
'org-babel-load-languages
|
||||||
|
(add-to-list 'org-babel-load-languages '(shell . t)))
|
||||||
|
|
||||||
|
(org-babel-do-load-languages
|
||||||
|
'org-babel-load-languages
|
||||||
|
(add-to-list 'org-babel-load-languages '(dot . t)))
|
||||||
|
|
||||||
|
(org-babel-do-load-languages
|
||||||
|
'org-babel-load-languages
|
||||||
|
(add-to-list 'org-babel-load-languages '(python . t)))
|
||||||
|
|
||||||
|
(add-to-list 'org-latex-packages-alist '("" "minted"))
|
||||||
|
(setq org-latex-listings 'minted)
|
||||||
|
(setq org-src-fontify-natively t)
|
||||||
|
|
||||||
|
(setq org-latex-pdf-process
|
||||||
|
'("pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
|
||||||
|
"bibtex documentation"
|
||||||
|
"pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
|
||||||
|
"pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"))
|
||||||
|
|
||||||
|
;; Citations
|
||||||
|
|
||||||
|
(org-add-link-type
|
||||||
|
"cite" 'ebib
|
||||||
|
(lambda (path desc format)
|
||||||
|
(cond
|
||||||
|
((eq format 'html)
|
||||||
|
(format "(<cite>%s</cite>)" path))
|
||||||
|
((eq format 'latex)
|
||||||
|
(if (or (not desc) (equal 0 (search "cite:" desc)))
|
||||||
|
(format "\\cite{%s}" path)
|
||||||
|
(format "\\cite[%s][%s]{%s}"
|
||||||
|
(cadr (split-string desc ";"))
|
||||||
|
(car (split-string desc ";")) path))))))
|
||||||
|
|
||||||
|
;; Functools
|
||||||
|
|
||||||
|
(defun pamhyr-version ()
|
||||||
|
"Return the contents of the pamhyr version file."
|
||||||
|
(with-temp-buffer
|
||||||
|
(insert-file-contents "../../VERSION")
|
||||||
|
(buffer-string)))
|
||||||
|
|
||||||
|
(defun pamhyr-current-file ()
|
||||||
|
(let ((lst (split-string (buffer-file-name) "/")))
|
||||||
|
(string-join (nthcdr (- (length lst) 3) lst) "/")))
|
||||||
|
|
@ -0,0 +1,10 @@
|
||||||
|
#! /bin/sh
|
||||||
|
|
||||||
|
# Build the PDF
|
||||||
|
|
||||||
|
emacs -Q -q -nw --batch \
|
||||||
|
--eval "(require 'org)" \
|
||||||
|
--eval "(require 'ox-latex)" \
|
||||||
|
--eval "(load-file \"../tools/setup.el\")" \
|
||||||
|
--file ./documentation.org \
|
||||||
|
-f org-latex-export-to-pdf
|
||||||
|
|
@ -0,0 +1 @@
|
||||||
|
../tools/ref.bib
|
||||||
|
|
@ -0,0 +1,20 @@
|
||||||
|
#+STARTUP: indent
|
||||||
|
|
||||||
|
#+INCLUDE: ../tools/macro.org
|
||||||
|
#+INCLUDE: ../tools/latex.org
|
||||||
|
|
||||||
|
#+TITLE: User documentation
|
||||||
|
#+SUBTITLE: Version: {{{version}}}
|
||||||
|
#+AUTHOR: {{{INRAE}}}
|
||||||
|
|
||||||
|
#+OPTIONS: toc:t
|
||||||
|
#+LANGUAGE: UKenglish
|
||||||
|
|
||||||
|
* TODO Over view
|
||||||
|
* TODO Get started
|
||||||
|
** Installation
|
||||||
|
*** Linux
|
||||||
|
*** Windows
|
||||||
|
* TODO Usage
|
||||||
|
|
||||||
|
{{{biblio}}}
|
||||||
Loading…
Reference in New Issue