doc: dev: Finish the documentations files section.

doc/dev/documentation.org

@@ -28,21 +28,26 @@
 #+OPTIONS: toc:t
 #+LANGUAGE: UKenglish
 
-* TODO Introduction
+* Introduction
 
-Pamhyr2 is free and open source 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 [[Setup the CI environment]]).
+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
@@ -55,9 +60,9 @@ https://doc.qt.io/qt-5/model-view-programming.html (last access
 *** TODO Linux
 *** TODO Windows
 ** TODO Setup the CI environment
-* TODO Documentation files
+* Documentation files
 
-This document and the user documentation are org[fn:org] files. This text file
+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
@@ -68,7 +73,7 @@ take a look at the different features used in these documents.
 [fn:emacs] The GNUEmacs project website: https://gnu.org/s/emacs/
 (last access 2023-09-15)
 
-** TODO Org-mode
+** Org-mode
 *** Document structure
 
 Org uses the =*= character to define a new document section. To add a
@@ -102,7 +107,32 @@ https://orgmode.org/org.html#Emphasis-and-Monospace (last access
 | =~code~=           | ~code~           |
 | =+strike-through+= | +strike-through+ |
 
-*** TODO Code block
+*** 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
+#+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.
+
+#+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
 
@@ -159,10 +189,42 @@ Macro apply:
 - Marco ={{{add(x,y)}}}=: {{{add(x,y)}}}
 - Marco ={{{emacs-version}}}=: {{{emacs-version}}}
 
-*** TODO Footnote
-*** TODO References
+*** 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 Export
 * TODO How to contribute?
 ** TODO Contribution rules
 ** TODO Translate

doc/tools/latex.org

@@ -17,3 +17,18 @@
 # -*- coding: utf-8 -*-
 
 #+LaTeX_CLASS: PamhyrDoc
+
+# Source code blocks
+#+LATEX_HEADER: \usepackage{minted}
+#+LATEX_HEADER: \usemintedstyle{emacs}
+#+LATEX_HEADER: \setminted[c]{fontsize=\footnotesize,encoding=utf8,linenos}
+#+LATEX_HEADER: \setminted[c++]{breaklines,fontsize=\footnotesize,encoding=utf8,linenos}
+#+LATEX_HEADER: \setminted[shell]{breaklines,fontsize=\footnotesize}
+#+LATEX_HEADER: \setminted[python]{breaklines,fontsize=\footnotesize,linenos}
+#+LATEX_HEADER: \setminted[scheme]{breaklines,fontsize=\footnotesize}
+#+LATEX_HEADER: \setminted[commun-lisp]{breaklines,fontsize=\footnotesize}
+#+LATEX_HEADER: \setminted[text]{breaklines,fontsize=\footnotesize}
+#+LATEX_HEADER: \setminted[llvm]{breaklines,fontsize=\footnotesize}
+
+#+LATEX_HEADER: \BeforeBeginEnvironment{minted}{\begin{tcolorbox}[boxsep=0pt, left=0.1cm, right=0.1cm, arc=0pt, boxrule=0.5pt, colback=white]}%
+#+LATEX_HEADER: \AfterEndEnvironment{minted}{\end{tcolorbox}}%

doc/tools/macro.org

@@ -31,5 +31,5 @@
 #+MACRO: file          =$1=
 
 # Biblio
-#+MACRO: cite          \cite{$1}
+#+MACRO: cite          [cite:$1]
 #+MACRO: biblio        \bibliography{documentation}

doc/tools/setup.el

@@ -1,6 +1,8 @@
 (require 'org)
 (require 'subr-x)
 
+;; LaTeX config
+
 (add-to-list
  'org-latex-classes
  '("PamhyrDoc"
@@ -11,6 +13,12 @@
    ("\\paragraph{%s}" . "\\paragraph*{%s}")
    ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
 
+(setq org-confirm-babel-evaluate nil)
+(setq org-latex-caption-above nil)
+
+(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"
@@ -18,6 +26,22 @@
         "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."