Merge branch 'doc' into refactoring.

doc/dev/build.sh

@@ -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

doc/dev/documentation.bib

@@ -0,0 +1 @@
+../tools/ref.bib

doc/dev/documentation.org

@@ -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}}}

doc/tools/PamhyrDoc.cls

@@ -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}

doc/tools/latex.org

@@ -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

doc/tools/macro.org

@@ -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

doc/tools/setup.el

@@ -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) "/")))

doc/users/build.sh

@@ -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

doc/users/documentation.bib

@@ -0,0 +1 @@
+../tools/ref.bib

doc/users/documentation.org

@@ -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}}}