Pamhyr2/doc/dev/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

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

#+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 {{{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=. Some org-mode configuration
used in documentations files are define in =/doc/tools/=:
- {{{file(PamhyrDoc.cls)}}}: The \LaTeX theme
- {{{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

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

{{{biblio}}}