documentation.org

# 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

* TODO Introduction

Pamhyr2 is free and open source 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 [[Setup the CI environment]]).

[fn:qt-arch] Qt Model/View documentation:
https://doc.qt.io/qt-5/model-view-programming.html (last access
2023-09-15)

* TODO Architecture
** TODO Model
** TODO Solver
** TODO View
** TODO Unit tests
** TODO The debug mode
* TODO Build the project
** TODO Building packages
*** TODO Linux
*** TODO Windows
** TODO Setup the CI environment
* TODO Documentation files

This document and the user documentation are org[fn: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)

** TODO 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+ |

*** TODO Code block

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

*** TODO Footnote
*** TODO References

** TODO Export
* TODO How to contribute?
** TODO Contribution rules
** TODO Translate
** TODO Code contribution

{{{biblio}}}