diff --git a/doc/dev/documentation.org b/doc/dev/documentation.org index 846a718e129da1157beac6fdd3857e3d04890577..aaf32969b1e6d0cd9194c46cef4da7ec2daff5eb 100644 --- a/doc/dev/documentation.org +++ b/doc/dev/documentation.org @@ -28,21 +28,26 @@ #+OPTIONS: toc:t #+LANGUAGE: UKenglish -* TODO 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]]). +* 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 @@ -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 diff --git a/doc/tools/latex.org b/doc/tools/latex.org index 2e655049bbd0199cfb896cc32ae0ca6209acdc69..06263f8510489f4bf8a86832725d4d081c54efee 100644 --- a/doc/tools/latex.org +++ b/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}}% diff --git a/doc/tools/macro.org b/doc/tools/macro.org index 2f897ae4a55be481da8bd06ceec449c9c969f384..fb760c9f1ee851ecd6f406899b8296ffa051a123 100644 --- a/doc/tools/macro.org +++ b/doc/tools/macro.org @@ -31,5 +31,5 @@ #+MACRO: file =$1= # Biblio -#+MACRO: cite \cite{$1} +#+MACRO: cite [cite:$1] #+MACRO: biblio \bibliography{documentation} diff --git a/doc/tools/setup.el b/doc/tools/setup.el index 81335dd328cd523cbd3272f1d10963819bbe1a45..54a3517bc72453d8c0833cd5f6997526248ca090 100644 --- a/doc/tools/setup.el +++ b/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."