diff --git a/doc/dev/build.sh b/doc/dev/build.sh new file mode 100755 index 0000000000000000000000000000000000000000..476dd5adeed4c75818c2df2f192bde841fb030af --- /dev/null +++ b/doc/dev/build.sh @@ -0,0 +1,10 @@ +#! /bin/sh + +# Build the PDF + +emacs -Q -q -nw --batch \ + --eval "(require 'org)" \ + --eval "(require 'ox-latex)" \ + --eval "(load-file \"../tools/setup.el\")" \ + --file ./documentation.org \ + -f org-latex-export-to-pdf diff --git a/doc/dev/documentation.bib b/doc/dev/documentation.bib new file mode 120000 index 0000000000000000000000000000000000000000..8319e14918166dd403e85b04687c81e9cb9ee559 --- /dev/null +++ b/doc/dev/documentation.bib @@ -0,0 +1 @@ +../tools/ref.bib \ No newline at end of file diff --git a/doc/dev/documentation.org b/doc/dev/documentation.org new file mode 100644 index 0000000000000000000000000000000000000000..f078bbb75665097feb5aee65babd5549b43f0314 --- /dev/null +++ b/doc/dev/documentation.org @@ -0,0 +1,551 @@ +# 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 + +#+NAME: attr_wrap +#+HEADER: :var width="\\textwidth" +#+HEADER: :var caption="" +#+HEADER: :var smallcaption="" +#+HEADER: :var name="" +#+HEADER: :var data="" +#+HEADER: :var float="nil" +#+BEGIN_SRC sh :results output :exports none + echo "#+CAPTION[$smallcaption]: $caption" + echo "#+NAME: $name" + echo "#+ATTR_LATEX: :width $width :float $float" + echo "$data" +#+END_SRC + +#+BEGIN_abstract +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. +#+END_abstract + +* 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 + +Pamhyr2 architecture is based on Qt Model/View programming[fn:qt-mv] architecture. + +#+name: graph-pipeline +#+header: :results drawer +#+header: :exports results +#+header: :post attr_wrap(width="12cm", data=*this*, name="graph-pipeline", caption="Pamhyr2 solver execution pipeline architecture scheme", float="t") +#+begin_src dot :file "images/graph-pipeline.png" :cache no + digraph { + node[colorscheme=set19,shape=box,style="filled",fillcolor=9]; + + subgraph cluster0 { + label="Pamhyr2" + config[label="Config",fillcolor=5]; + model[label="Model",fillcolor=2]; + obj[label="Solver",fillcolor=6]; + results[label="Results",fillcolor=2]; + view[label="View",fillcolor=1]; + + results -> model[style="dotted"]; + results -> obj[style="dotted"]; + } + + config -> obj[label=""]; + obj -> model; + + subgraph cluster1{ + label="System"; + in[label="Solver input files",shape=note]; + out[label="Solver output files",shape=note]; + bin[label="Solver binary",shape=note]; + } + + obj -> in[label="Write"]; + bin -> in[label="Read"]; + obj -> bin[label="Execute"]; + bin -> out[label="Write"]; + obj -> results[label="Create"]; + results -> out[label="Read"]; + view -> model; + view -> results; + } +#+end_src + +#+name: graph-architecture +#+header: :results drawer +#+header: :exports results +#+header: :post attr_wrap(width="7cm", data=*this*, name="graph-architecture", caption="Pamhyr2 Model/View architecture scheme (inspired by Qt Model/View architecture [[https://doc.qt.io/qt-5/model-view-programming.html]])", float="t") +#+begin_src dot :file "images/graph-architecture.png" :cache no + digraph { + node[colorscheme=set19,shape=box,style="filled",fillcolor=white]; + + save[label="Pamhyr save",fillcolor="9",shape=note]; + model[label="Model",fillcolor="2"]; + view[label="View",fillcolor="1"]; + delegate[label="Delegate",fillcolor="3"]; + undocommand[label="UndoCommand",fillcolor="4"]; + user[label="User",shape=ellipse]; + + model -> save[label="Save"]; + save -> model[label="Load"]; + + model -> view[label="Rendering"]; + view -> delegate[label="Rendering"]; + delegate -> undocommand[label="Create"]; + undocommand -> model[label="Modify"] + + view -> user[label="Vizualize"]; + user -> delegate[label="Modify"]; + } +#+end_src + +#+name: graph-model +#+header: :results drawer +#+header: :exports results +#+header: :post attr_wrap(width="16cm", data=*this*, name="graph-model", caption="Pamhyr2 Model architecture scheme", float="t") +#+begin_src dot :file "images/graph-model.png" :cache no + digraph { + node[colorscheme=set19,shape=box,style="filled",fillcolor="2"]; + + study[label="Study"]; + river[label="River"]; + + subgraph cluster00 { + label="Network" + rnode[label="RiverNode"]; + redge[label="RiverReach"]; + } + + frictionlist[label="FrictionList"]; + + subgraph cluster01 { + label="Stricklers"; + stricklers[label="Stricklers"]; + stricklerslist[label="StricklersList"]; + } + subgraph cluster02 { + label="BoundaryCondition"; + boundaryconditionlist[label="BoundaryConditionList"]; + boundarycondition[label="BoundaryCondition"]; + } + subgraph cluster03 { + label="LateralContribution"; + lateralcontributionlist[label="LateralContributionList"]; + lateralcontribution[label="LateralContribution"]; + } + subgraph cluster04 { + label="InitialConditions"; + initialconditionsdict[label="InitialConditionsDict"]; + initialconditions[label="InitialConditions"]; + } + + solverparameterslist[label="SolverParametersList"]; + + subgraph cluster05 { + label="Sediment"; + sedimentlayerlist[label="SedimentLayerList"]; + sedimentlayer[label="SedimentLayer"]; + layer[label="Layer"]; + } + + subgraph cluster06 { + label="Greometry" + georeach[label="Reach"]; + geocrosssection[label="Cross-section"]; + geopoint[label="Point"]; + } + + study -> river; + river -> rnode; + river -> redge; + redge -> rnode; + river -> boundaryconditionlist -> boundarycondition -> rnode; + river -> lateralcontributionlist -> lateralcontribution -> redge; + river -> initialconditionsdict -> initialconditions; + initialconditions -> redge; + river -> stricklerslist -> stricklers; + river -> solverparameterslist; + river -> sedimentlayerlist -> sedimentlayer -> layer; + redge -> frictionlist -> stricklers; + redge -> georeach -> geocrosssection -> geopoint; + geocrosssection -> sedimentlayer; + geopoint -> sedimentlayer; + + } +#+end_src + +[fn:qt-mv] The Qt Model/View documentation web page: +https://doc.qt.io/qt-5/model-view-programming.html + +** TODO Model +** TODO View +*** TODO UI file +*** TODO Window class +** TODO UndoCommand +** TODO Table +** TODO Plot +** TODO Solver +** 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 +{{{file(packages)}}} 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 [[linux-env-deb]] for Debian and derived system). Finally, +run the {{{file(linux.sh)}}} script (see Listing [[linux-pkg]]). + +#+NAME: linux-env-deb +#+CAPTION: Install environment on GNU/Linux +#+begin_src shell +sudo apt install python3.8 +python3 -m pip install venv +python3 -m pip install pyinstaller +#+end_src + +#+NAME: linux-pkg +#+CAPTION: Build GNU/Linux package +#+begin_src shell +cd packages +./linux.sh +#+end_src + +*** Windows + +To make the Windows packages you have two choice: If you use Windows +you can use the script {{{file(packages/windows.bat)}}}, other else +you can use the script {{{file(packages/wine.sh)}}}. Each script need +a specific software environment. + +On windows, you needs python on version 3.8, pyinstaller and +NSIS[fn:nsis] installed. On GNU/Linux you need wget, wine and +winetricks installed. + +[fn:nsis] The NSIS web site: https://sourceforge.net/projects/nsis/ + +** 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. + +#+OPTIONS: float:nil +#+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 {{{file(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=. 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 [[texlive-install]]. + +#+NAME: texlive-install +#+CAPTION: Installation command for texlive full on Debian system +#+begin_src shell + sudo apt install texlive-full +#+end_src + +Some org-mode configuration used in documentations files are define in +=/doc/tools/=: +- {{{file(PamhyrDoc.cls)}}}: The {{{latex}}} document class +- {{{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? + +Pamhyr2 is free software: you can redistribute it and/or modify it +under the terms of the GNU General Public License[fn:license], either +version 3 of the License, or any later version. + +[fn:license] The GPLv3 web page: +https://www.gnu.org/licenses/gpl-3.0.en.html + +** 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[fn:p2-gitlab], 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[fn: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(AUTHORS)}}} file +and respect the Listing [[auth-format]] format. You can update this file +information for following contribution. + +#+NAME: auth-format +#+CAPTION: =AUTHORS= file format +#+begin_src text +<first name> <last name> [(optional) email], <organisation>, <years> +#+end_src + +#+CAPTION: Current =AUTHORS= file +#+INCLUDE: "../../AUTHORS" src text + +[fn:p2-gitlab] The Pamhyr2 Gitlab project page: +https://gitlab.irstea.fr/theophile.terraz/pamhyr +[fn:inrae] The INRAE web site: https://www.inrae.fr/ + +** Translate + +You can improve or add translation for the project. To contribute to +Pamhyr2 translate, you need to use Qt Linguist[fn:qt-linguist]. Open +Qt-linguist and edite the translation ({{{file(.ts)}}}) file, finally, +commit the new version of file and make a merge request. + +If you want add a new language, edit the script +{{{file(src/lang/create_ts.sh)}}} like Listing [[ts-it]]. Run the script +and open the new file with Qt-linguist, setup target language (Figure +[[qt-linguist-setup]]) and complete translation. Finally, commit the new +file and make a merge request. + +#+NAME: ts-it +#+CAPTION: Example of modified {{{file(src/lang/create_ts.sh)}}} to add italian (it) translate for Pamhyr2 +#+begin_src shell + ... + LANG="fr it" + ... +#+end_src + +#+NAME: qt-linguist-setup +#+ATTR_HTML: :width 8cm +#+ATTR_LATEX: :width 8cm +#+CAPTION: Qt linguist lang setup example with italian. +[[../images/Qt-linguist-setup-lang.png]] + +[fn:qt-linguist] The Qt linguist documentation web page: +https://doc.qt.io/qt-5/qtlinguist-index.html (last access 2023-09-18) + +** Code contribution + +If you are developper you can improve and/or add features to +Pamhyr2. Please, follow the architecture described in section +[[Architecture]] as closely as possible. Keep the code simple, clear and +efficient as possible. The master branch is reserved for the project +maintainer; you can create a new branch or fork the project before the +request. + + +{{{biblio}}} diff --git a/doc/dev/images/.gitkeep b/doc/dev/images/.gitkeep new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/doc/images/GPLv3_Logo.png b/doc/images/GPLv3_Logo.png new file mode 100644 index 0000000000000000000000000000000000000000..1f6ddf89ad8e956bf674a98e9f0cb08d0f29e651 Binary files /dev/null and b/doc/images/GPLv3_Logo.png differ diff --git a/doc/images/Qt-linguist-setup-lang.png b/doc/images/Qt-linguist-setup-lang.png new file mode 100644 index 0000000000000000000000000000000000000000..9ba375d1f4a0e451fd0055c85182353eda959d18 Binary files /dev/null and b/doc/images/Qt-linguist-setup-lang.png differ diff --git a/doc/images/riverly.png b/doc/images/riverly.png new file mode 100644 index 0000000000000000000000000000000000000000..14a38a2f43f67e0aa88cb5b692dc110c681a9d2d Binary files /dev/null and b/doc/images/riverly.png differ diff --git a/doc/tools/PamhyrDoc.cls b/doc/tools/PamhyrDoc.cls new file mode 100644 index 0000000000000000000000000000000000000000..a2cc8473734f6ede033a0d85a9cff3b4eb50103e --- /dev/null +++ b/doc/tools/PamhyrDoc.cls @@ -0,0 +1,163 @@ +\ProvidesClass{Pamhyr}[Pamhyr class] +\NeedsTeXFormat{LaTeX2e} +\ProcessOptions\relax +\LoadClass[11pt,a4paper]{article} + +\usepackage[hmargin=2cm, vmargin=3cm]{geometry} +\usepackage[british,UKenglish,USenglish,english,american]{babel} +\usepackage[T1]{fontenc} +\usepackage{times} +\usepackage[usenames,dvipsnames]{xcolor} +\usepackage[absolute]{textpos} +\usepackage{titlesec} +\usepackage{amssymb} +\usepackage{tcolorbox} + +\usepackage{enumitem} +\setlist[enumerate]{itemsep=-0.5em} +\setlist[itemize]{itemsep=-0.5em} + +%% +%% Bibtex +%% + +\bibliographystyle{plain} + +%% +%% Colors +%% + +\definecolor{primary}{HTML}{212121} +\definecolor{lightheadings}{HTML}{5c5c5c} +\definecolor{headings}{HTML}{212121} +\definecolor{links}{HTML}{e12121} + +%% +%% Title +%% + +\setlength{\columnsep}{20pt} +\setlength{\parskip}{0pt} %% inter paragraph space + +\renewcommand{\maketitle}{ + { + \centering + { + \fontsize{35}{40} + \selectfont + \scshape + Pamhyr2 \\ + \medskip + } + { + %\centering + \scshape + \fontsize{20pt}{24pt} + \selectfont + A graphical user interface for 1D hydro-sedimentary modelling + of rivers \\ + \medskip + } + \rule{3cm}{0.4pt}\\ + \vspace{0.3cm} + { + %\centering + \scshape + \fontsize{26pt}{24pt} + \selectfont + \@title \\ + Document licence: GPLv3 \\ + \medskip + \includegraphics[width=3cm]{../images/GPLv3_Logo.png} \\ + \medskip + \fontsize{14pt}{16pt} + \selectfont + © \@author \\ + \medskip + } + { + %\centering + %\scshape + \fontsize{12pt}{14pt} + \selectfont + \@date + %\medskip + }\\ + \vspace{0.3cm} + \rule{3cm}{0.4pt}\\ + \vspace{0.3cm} + { + \begin{minipage}[h]{0.24\textwidth} + \includegraphics[width=4cm]{../../src/View/ui/ressources/Logo-INRAE.png} + \end{minipage} + \begin{minipage}[h]{0.24\textwidth} + \includegraphics[width=4cm]{../images/riverly.png} + \end{minipage} + }\\ + \vspace{0.3cm} + %%\rule{\textwidth}{0.4pt} + %%\newpage + } +} + + +%% +%% Texttt +%% + +\usepackage[htt]{hyphenat} % Make texttt split at end of line + +%% +%% Verbatim +%% + +\AtBeginEnvironment{verbatim}{\footnotesize} + +%% Add box arrond of verbatim +\BeforeBeginEnvironment{verbatim}{\begin{tcolorbox}[boxsep=0pt, left=0.1cm, right=0.1cm, arc=0pt, boxrule=0.5pt, colback=white]}% +\AfterEndEnvironment{verbatim}{\end{tcolorbox}}% + +\makeatletter +\AtBeginEnvironment{verbatim}{\dontdofcolorbox} + +\def\dontdofcolorbox{\renewcommand\fcolorbox[4][]{##4}} +\makeatother + +%% +%% Source code blocks +%% + +%% Use minted +\usepackage{minted} +\usemintedstyle{tango} +\setminted[c]{fontsize=\footnotesize,encoding=utf8,linenos} +\setminted[c++]{breaklines,fontsize=\footnotesize,encoding=utf8,linenos} +\setminted[python]{breaklines,fontsize=\footnotesize,encoding=utf8,linenos} +\setminted[shell]{breaklines,fontsize=\footnotesize,encoding=utf8} +\setminted[scheme]{breaklines,fontsize=\footnotesize,encoding=utf8} +\setminted[commun-lisp]{breaklines,fontsize=\footnotesize,encoding=utf8} +\setminted[text]{breaklines,fontsize=\footnotesize,encoding=utf8} +\setminted[llvm]{breaklines,fontsize=\footnotesize,encoding=utf8} + +%% Add box arrond of minted +\BeforeBeginEnvironment{minted}{\begin{tcolorbox}[boxsep=0pt, left=0.1cm, right=0.1cm, arc=0pt, boxrule=0.5pt, colback=white]}% +\AfterEndEnvironment{minted}{\end{tcolorbox}}% + +\makeatletter +\AtBeginEnvironment{minted}{\dontdofcolorbox} + +\def\dontdofcolorbox{\renewcommand\fcolorbox[4][]{##4}} +\makeatother + + +%% +%% Water mark +%% + +%% FIXME: Delete me for the first realease +\usepackage{draftwatermark} +\SetWatermarkLightness{0.8} +\SetWatermarkAngle{25} +\SetWatermarkScale{3} +\SetWatermarkFontSize{1cm} +\SetWatermarkText{Work in progress} diff --git a/doc/tools/latex.org b/doc/tools/latex.org new file mode 100644 index 0000000000000000000000000000000000000000..2e655049bbd0199cfb896cc32ae0ca6209acdc69 --- /dev/null +++ b/doc/tools/latex.org @@ -0,0 +1,19 @@ +# latex.org -- Pamhyr documentation latex config +# 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 -*- + +#+LaTeX_CLASS: PamhyrDoc diff --git a/doc/tools/macro.org b/doc/tools/macro.org new file mode 100644 index 0000000000000000000000000000000000000000..9c59153f3fe0f75d19005df179eafda887f4eae7 --- /dev/null +++ b/doc/tools/macro.org @@ -0,0 +1,51 @@ +# macro.org -- Pamhyr documentation macro +# 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 -*- + +# Constant name +#+MACRO: oldPamhyr PAMHyR +#+MACRO: Pamhyr Pamhyr2 +#+MACRO: Mage Mage +#+MACRO: Rubarbe RubarBE +#+MACRO: Inrae INRAE +#+MACRO: latex \LaTeX + +# Information +#+MACRO: version (eval (pamhyr-version)) +#+MACRO: current-file (eval (pamhyr-current-file)) + +# Special format +#+MACRO: file =$1= + +# Biblio +#+MACRO: cite [cite:$1] +#+MACRO: biblio \bibliography{documentation} + +# Wrapper +#+NAME: attr_wrap +#+HEADER: :var width="\\textwidth" +#+HEADER: :var caption="" +#+HEADER: :var smallcaption="" +#+HEADER: :var name="" +#+HEADER: :var data="" +#+HEADER: :var float="nil" +#+BEGIN_SRC sh :results output :exports none + echo "#+CAPTION[$smallcaption]: $caption" + echo "#+NAME: $name" + echo "#+ATTR_LATEX: :width $width :float $float" + echo "$data" +#+END_SRC diff --git a/doc/tools/ref.bib b/doc/tools/ref.bib new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/doc/tools/setup.el b/doc/tools/setup.el new file mode 100644 index 0000000000000000000000000000000000000000..027e5700dd360bf37e1484d635446d7b81d9f8df --- /dev/null +++ b/doc/tools/setup.el @@ -0,0 +1,66 @@ +(require 'org) +(require 'subr-x) + +;; LaTeX config + +(add-to-list + 'org-latex-classes + '("PamhyrDoc" + "\\documentclass{../tools/PamhyrDoc}" + ("\\section{%s}" . "\\section*{%s}") + ("\\subsection{%s}" . "\\subsection*{%s}") + ("\\subsubsection{%s}" . "\\subsubsection*{%s}") + ("\\paragraph{%s}" . "\\paragraph*{%s}") + ("\\subparagraph{%s}" . "\\subparagraph*{%s}"))) + +(setq org-confirm-babel-evaluate nil) +(setq org-latex-caption-above nil) + +(org-babel-do-load-languages + 'org-babel-load-languages + (add-to-list 'org-babel-load-languages '(shell . t))) + +(org-babel-do-load-languages + 'org-babel-load-languages + (add-to-list 'org-babel-load-languages '(dot . t))) + +(org-babel-do-load-languages + 'org-babel-load-languages + (add-to-list 'org-babel-load-languages '(python . t))) + +(add-to-list 'org-latex-packages-alist '("" "minted")) +(setq org-latex-listings 'minted) +(setq org-src-fontify-natively t) + +(setq org-latex-pdf-process + '("pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f" + "bibtex documentation" + "pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f" + "pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f")) + +;; Citations + +(org-add-link-type + "cite" 'ebib + (lambda (path desc format) + (cond + ((eq format 'html) + (format "(<cite>%s</cite>)" path)) + ((eq format 'latex) + (if (or (not desc) (equal 0 (search "cite:" desc))) + (format "\\cite{%s}" path) + (format "\\cite[%s][%s]{%s}" + (cadr (split-string desc ";")) + (car (split-string desc ";")) path)))))) + +;; Functools + +(defun pamhyr-version () + "Return the contents of the pamhyr version file." + (with-temp-buffer + (insert-file-contents "../../VERSION") + (buffer-string))) + +(defun pamhyr-current-file () + (let ((lst (split-string (buffer-file-name) "/"))) + (string-join (nthcdr (- (length lst) 3) lst) "/"))) diff --git a/doc/users/build.sh b/doc/users/build.sh new file mode 100755 index 0000000000000000000000000000000000000000..476dd5adeed4c75818c2df2f192bde841fb030af --- /dev/null +++ b/doc/users/build.sh @@ -0,0 +1,10 @@ +#! /bin/sh + +# Build the PDF + +emacs -Q -q -nw --batch \ + --eval "(require 'org)" \ + --eval "(require 'ox-latex)" \ + --eval "(load-file \"../tools/setup.el\")" \ + --file ./documentation.org \ + -f org-latex-export-to-pdf diff --git a/doc/users/documentation.bib b/doc/users/documentation.bib new file mode 120000 index 0000000000000000000000000000000000000000..8319e14918166dd403e85b04687c81e9cb9ee559 --- /dev/null +++ b/doc/users/documentation.bib @@ -0,0 +1 @@ +../tools/ref.bib \ No newline at end of file diff --git a/doc/users/documentation.org b/doc/users/documentation.org new file mode 100644 index 0000000000000000000000000000000000000000..1907bf9368d4f2c5002e5e7e62ca9855992aa042 --- /dev/null +++ b/doc/users/documentation.org @@ -0,0 +1,20 @@ +#+STARTUP: indent + +#+INCLUDE: ../tools/macro.org +#+INCLUDE: ../tools/latex.org + +#+TITLE: User documentation +#+SUBTITLE: Version: {{{version}}} +#+AUTHOR: {{{INRAE}}} + +#+OPTIONS: toc:t +#+LANGUAGE: UKenglish + +* TODO Over view +* TODO Get started +** Installation +*** Linux +*** Windows +* TODO Usage + +{{{biblio}}}