documentation.org



Developers documentation
#
#
#
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 <a href=”Setup the CI
  environment”>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)
Architecture
Model
Solver
View
Unit tests
The debug mode
Build the project
Building packages
Linux
Windows
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)].
* Top level headline
** Second level
*** Third level
    some text
*** Third level
    more text
* Another top level headline

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:
#+CAPTION: Get os type name in Python code
import os

print(f"Document build on system: {os.name}")

If you use GNUEmacs, it is also possible to run the code inside a
  block and export (or not) the reuslts in the document.
import os

print(f"Document build on system: {os.name}")

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:
# Add latex in line
#+LATEX: <my line of latex>

# Add multiple line of LaTeX
<my latex here>

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.
# Exemple of macro définition

#+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)]:
The Org website[fn:1] now looks a lot better than it used to.
...
[fn:1] The link is: https://orgmode.org

or:
The Org website[fn:: The link is: https://orgmode.org] now looks
a lot better than it used to.
...

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

How to contribute?
Contribution rules
Translate
Code contribution
{{{biblio}}}