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 @@
#+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
......
......@@ -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}}%
......@@ -31,5 +31,5 @@
#+MACRO: file =$1=
# Biblio
#+MACRO: cite \cite{$1}
#+MACRO: cite [cite:$1]
#+MACRO: biblio \bibliography{documentation}
(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."
......
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