11 KiB

Raw Blame History

Developers documentation

Introduction
Architecture
- Model
- Solver
- View
- Unit tests
- The debug mode
Build the project
- Building packages
  - GNU/Linux
  - Windows
- Setup the CI environment
Documentation files
- Org-mode
- Export
How to contribute?

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.

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 for details). The architecture of project code follow the Qt Model/View architecture ¹ (see details in section /parouby/Pamhyr2/src/commit/8429d04b3ab5e3c6aa1c9b7367940c8d4e4065f0/doc/dev/Architecture). Pamhyr2 packages can be build manually (see section /parouby/Pamhyr2/src/commit/8429d04b3ab5e3c6aa1c9b7367940c8d4e4065f0/doc/dev/Building%20packages), but there are automatically build with the gitlab-ci (see the section [[Setup the CI environment]]). Documentation files are written with org-mode², let see section /parouby/Pamhyr2/src/commit/8429d04b3ab5e3c6aa1c9b7367940c8d4e4065f0/doc/dev/Documentation%20files. Finally, to see the contribution rules, see the section /parouby/Pamhyr2/src/commit/8429d04b3ab5e3c6aa1c9b7367940c8d4e4065f0/doc/dev/How%20to%20contribute?.

TODO Architecture

TODO Model

TODO Solver

TODO View

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 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 /parouby/Pamhyr2/src/commit/8429d04b3ab5e3c6aa1c9b7367940c8d4e4065f0/doc/dev/linux-env-deb for Debian and derived system). Finally, run the script (see Listing /parouby/Pamhyr2/src/commit/8429d04b3ab5e3c6aa1c9b7367940c8d4e4065f0/doc/dev/linux-pkg).

sudo apt install python3.8
python3 -m pip install venv
python3 -m pip install pyinstaller

Install environment on GNU/Linux

cd packages
./linux.sh

Build GNU/Linux package

Windows

To make the Windows packages you have two choice: If you use Windows you can use the script , other else you can use the script . Each script need a specific software environment.

On windows, you needs python on version 3.8, pyinstaller and NSIS³ installed. On GNU/Linux you need wget, wine and winetricks installed.

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⁴ text editor, but can be edited with any text editor. Here we take a look at the different features used in these documents.

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
#+begin_src python
import os

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

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

Get os type name in Python code

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
#+BEGIN_EXPORT latex
<my latex here>
#+END_EXPORT

It is also possible to add specific +LATEX_HEADER=. In this document we use the file 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. 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)}}}:
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 bib file is in and use for developers and user documentation. In document, use {{{cite(<name>)}}} to cite a paper.

Export

To export the files, a 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 /parouby/Pamhyr2/src/commit/8429d04b3ab5e3c6aa1c9b7367940c8d4e4065f0/doc/dev/texlive-install.

  sudo apt install texlive-full

Installation command for texlive full on Debian system

Some org-mode configuration used in documentations files are define in /doc/tools/:

: The {{{latex}}} document class
: Available macro
: {{{latex}}} configutation for documentations files
: GNUEmacs configuration to build documentations
: Bibtex files for documentations files

TODO How to contribute?

Pamhyr2 is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License⁵, either version 3 of the License, or any later version.

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⁶, 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⁷, 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 and respect the Listing /parouby/Pamhyr2/src/commit/8429d04b3ab5e3c6aa1c9b7367940c8d4e4065f0/doc/dev/auth-format format. You can update this file information for following contribution.

<first name> <last name> [(optional) email], <organisation>, <years>

AUTHORS file format

TODO Translate

TODO Code contribution

{{{biblio}}}

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

The org-mode website: https://orgmode.org/ (last access 2023-09-15)

The NSIS web site: https://sourceforge.net/projects/nsis/

⁴

The GNUEmacs project website: https://gnu.org/s/emacs/ (last access 2023-09-15)

⁵

The GPLv3 web page: https://www.gnu.org/licenses/gpl-3.0.en.html

⁶

The Pamhyr2 Gitlab project page: https://gitlab.irstea.fr/theophile.terraz/pamhyr

⁷

The INRAE web site: https://www.inrae.fr/

11 KiB Raw Blame History