Commit 100f98c5 authored by Pierre-Antoine Rouby's avatar Pierre-Antoine Rouby
Browse files

doc: dev: Finish the documentations files section.

Showing with 120 additions and 19 deletions
+120 -19
...@@ -28,21 +28,26 @@ ...@@ -28,21 +28,26 @@
#+OPTIONS: toc:t #+OPTIONS: toc:t
#+LANGUAGE: UKenglish #+LANGUAGE: UKenglish
* TODO Introduction * Introduction
Pamhyr2 is free and open source graphical user interface (GUI) for 1D Pamhyr2 is free and open source software (FOSS) graphical user
hydro-sedimentary modelling of rivers developed in Python (with interface (GUI) for 1D hydro-sedimentary modelling of rivers developed
version 3.8). It use PyQt at version 5 and matplotlib in version 3.4.1 in Python (with version 3.8). It use PyQt at version 5 and matplotlib
or later for the user insterface (see {{{file(/requirements.txt)}}} in version 3.4.1 or later for the user insterface (see
for details). The architecture of project code follow the Qt {{{file(/requirements.txt)}}} for details). The architecture of
Model/View architecture [fn:qt-arch] (see details in section project code follow the Qt Model/View architecture [fn:qt-arch] (see
[[Architecture]]). Pamhyr2 packages can be build manually (see section details in section [[Architecture]]). Pamhyr2 packages can be build
[[Building packages]]), but there are automatically build with the manually (see section [[Building packages]]), but there are automatically
gitlab-ci (see [[Setup the CI environment]]). 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: [fn:qt-arch] Qt Model/View documentation:
https://doc.qt.io/qt-5/model-view-programming.html (last access https://doc.qt.io/qt-5/model-view-programming.html (last access
2023-09-15) 2023-09-15)
[fn:org] The org-mode website: https://orgmode.org/ (last access
2023-09-15)
* TODO Architecture * TODO Architecture
** TODO Model ** TODO Model
...@@ -55,9 +60,9 @@ https://doc.qt.io/qt-5/model-view-programming.html (last access ...@@ -55,9 +60,9 @@ https://doc.qt.io/qt-5/model-view-programming.html (last access
*** TODO Linux *** TODO Linux
*** TODO Windows *** TODO Windows
** TODO Setup the CI environment ** 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: format is formatted so that it can be exported in different formats:
PDF (with latex), ODT, HTML, etc. It was originally designed for the 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 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. ...@@ -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/ [fn:emacs] The GNUEmacs project website: https://gnu.org/s/emacs/
(last access 2023-09-15) (last access 2023-09-15)
** TODO Org-mode ** Org-mode
*** Document structure *** Document structure
Org uses the =*= character to define a new document section. To add a 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 ...@@ -102,7 +107,32 @@ https://orgmode.org/org.html#Emphasis-and-Monospace (last access
| =~code~= | ~code~ | | =~code~= | ~code~ |
| =+strike-through+= | +strike-through+ | | =+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 *** Latex
...@@ -159,10 +189,42 @@ Macro apply: ...@@ -159,10 +189,42 @@ Macro apply:
- Marco ={{{add(x,y)}}}=: {{{add(x,y)}}} - Marco ={{{add(x,y)}}}=: {{{add(x,y)}}}
- Marco ={{{emacs-version}}}=: {{{emacs-version}}} - Marco ={{{emacs-version}}}=: {{{emacs-version}}}
*** TODO Footnote *** Footnotes
*** TODO References
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 How to contribute?
** TODO Contribution rules ** TODO Contribution rules
** TODO Translate ** TODO Translate
......
...@@ -17,3 +17,18 @@ ...@@ -17,3 +17,18 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
#+LaTeX_CLASS: PamhyrDoc #+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}}%
...@@ -31,5 +31,5 @@ ...@@ -31,5 +31,5 @@
#+MACRO: file =$1= #+MACRO: file =$1=
# Biblio # Biblio
#+MACRO: cite \cite{$1} #+MACRO: cite [cite:$1]
#+MACRO: biblio \bibliography{documentation} #+MACRO: biblio \bibliography{documentation}
(require 'org) (require 'org)
(require 'subr-x) (require 'subr-x)
;; LaTeX config
(add-to-list (add-to-list
'org-latex-classes 'org-latex-classes
'("PamhyrDoc" '("PamhyrDoc"
...@@ -11,6 +13,12 @@ ...@@ -11,6 +13,12 @@
("\\paragraph{%s}" . "\\paragraph*{%s}") ("\\paragraph{%s}" . "\\paragraph*{%s}")
("\\subparagraph{%s}" . "\\subparagraph*{%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 (setq org-latex-pdf-process
'("pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f" '("pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
...@@ -18,6 +26,22 @@ ...@@ -18,6 +26,22 @@
"pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f" "pdflatex -shell-escape -interaction nonstopmode -output-directory %o %f"
"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 () (defun pamhyr-version ()
"Return the contents of the pamhyr version file." "Return the contents of the pamhyr version file."
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment