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