From 94e07ba4c83f7dc1a43862edb8f24c6433d79382 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Riette?= <sebastien.riette@meteo.fr>
Date: Thu, 20 Oct 2022 10:39:16 +0200
Subject: [PATCH] S. Riette 20 oct 2022: pdf export of the doc

---
 .gitignore                       |   4 +
 docs/CodingNorms.md              |  10 +--
 docs/Developer.md                |  16 ++--
 docs/Integrator.md               |  22 ++---
 docs/Offline.md                  |  14 ++--
 docs/PHYEX.md                    |  15 ++--
 docs/Plugging.md                 |  10 +--
 docs/Tools.md                    |  23 +++---
 tools/generate_standalone_doc.sh | 135 +++++++++++++++++++++++++++++++
 9 files changed, 191 insertions(+), 58 deletions(-)
 create mode 100755 tools/generate_standalone_doc.sh

diff --git a/.gitignore b/.gitignore
index 844de1003..8574b6017 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,3 +12,7 @@
 # VI temp files
 .*.swp
 .*.swo
+
+# Eclipse project files
+/.cproject
+/.project
diff --git a/docs/CodingNorms.md b/docs/CodingNorms.md
index 0b4ba34f4..2d67aaa8a 100644
--- a/docs/CodingNorms.md
+++ b/docs/CodingNorms.md
@@ -1,12 +1,10 @@
-# PHYEX coding norms documentation
+# PHYEX CODING NORMS DOCUMENTATION
 
-## ABOUT THIS DOCUMENT
+## About this section
 
-This document is intended for developers and integrators and describes the coding norms to use.
+This section is intended for developers and integrators and describes the coding norms to use.
 
-This document is written using the markdown language. With pandoc, it can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf).
-
-## CODING NORMS
+## Coding norms
 
 ### Namelists
 We must be able to reproduce (binary comparison of the output files) the model results before and after code modifications. It means that every modification must be controlled by a namelist key (with the exception of bug corrections).
diff --git a/docs/Developer.md b/docs/Developer.md
index 7f0549664..0a2043702 100644
--- a/docs/Developer.md
+++ b/docs/Developer.md
@@ -1,8 +1,8 @@
-# PHYEX developer documentation
+# PHYEX DEVELOPER DOCUMENTATION
 
-## ABOUT THIS DOCUMENT
+## About this section
 
-This document is intended for developers who want to contribute to the PHYEX package.
+This section is intended for developers who want to contribute to the PHYEX package.
 Developer who is interested in plugging the physics in a new model can refer to the Plugging documentation.
 The topics covered are as follows:
 
@@ -11,9 +11,7 @@ The topics covered are as follows:
   - [Contribution workflow for Méso-NH developers](#contribution-workflow-for-mesonh-developers)
   - [Contribution workflow for other developers](#contribution-workflow-for-other-developers)
 
-This document is written using the markdown language. With pandoc, it can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf).
-
-## PACKAGE ORGANISATION
+## Package organisation
 
 The package contains two kinds of branches:
 
@@ -38,7 +36,7 @@ Here is a short description of the different generic branches:
   - testHUGE: modified source code to check the incomplete NPROMA feature
   - testprogs\_data: modified source code used to generate samples for the test programs (more on this topic in the [Offline documentation](./Offline.md))
 
-## CONTRIBUTION WORKFLOW FOR AROME and HARMONIE-AROME DEVELOPERS
+## Contribution workflow for AROME and HARMONIE-AROME developers
 
 The build systems are evolving.
 Until cycle 49t1 (included), the physics source code is directly included in the source code tree.
@@ -102,7 +100,7 @@ To build the model, you must:
 - dispatch the code contained in 'ext' into the subdirectories of 'arpifs'
 - remove the files listed in the PHYEX repository in the 'src/arome/gmkpack\_ignored\_files' file
 
-## CONTRIBUTION WORKFLOW FOR MESO-NH DEVELOPERS
+## Contribution workflow for MESO-NH developers
 
 The physics source code is embedded in the Méso-NH source code.
 
@@ -110,6 +108,6 @@ The physics source code comes directly from a mesonh specific branch (these bran
 
 Pull requests concerning the physics continue to follow the same path as before (ie pull requests are submitted to the Meso-NH repository). The Meso-NH integrator will submit a pull request to the PHYEX repository with only the relevant files.
 
-## CONTRIBUTION WORKFLOW FOR OTHER DEVELOPERS
+## Contribution workflow for other developers
 
 Other developers must work with source code coming directly from the master branch. They issue pull requests directly on this branch as usual with git repositories.
diff --git a/docs/Integrator.md b/docs/Integrator.md
index 94ce1e3ac..5716ceadb 100644
--- a/docs/Integrator.md
+++ b/docs/Integrator.md
@@ -1,12 +1,10 @@
-# PHYEX integrator documentation
+# PHYEX INTEGRATOR DOCUMENTATION
 
-## ABOUT THIS DOCUMENT
+## About this section
 
 This document is intended for integrators who are in charge of assembling contributions received through pull requests.
 
-This document is written using the markdown language. With pandoc, it can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf).
-
-## BRANCHES AND NORMS
+## Branches and norms
 
 Regarding array-syntax, the [applicable norm](./CodingNorms.md) depends on the branch:
 
@@ -17,7 +15,7 @@ Regarding array-syntax, the [applicable norm](./CodingNorms.md) depends on the b
 
 Pull requests can be received on all these kind of branches and must be merged into the master branch with according norm.
 
-## NORMAL WORKFLOW FOR A CONTRIBUTION DEVELOPED IN AROME AND HARMONIE-AROME
+## Normal workflow for a contribution developed in AROME and HARMONIE-AROME
 
 ### Scientific contributions until cycle 49t1
 
@@ -26,6 +24,7 @@ Pull requests can be received on all these kind of branches and must be merged i
 The pull request comes from the IAL integrator. It must be based on an arome specific branch.
 
 Details for point 6, the PHYEX administrator:
+
   - validates (see [below](#tests)) the contribution
   - integrates the contribution in the arome branch and merges it in the master branch
   - regularly, he tags a new (minor) version of the master branch
@@ -39,6 +38,7 @@ Details for point 6, the PHYEX administrator:
 The pull request comes directly from a developer. It must be based on an arome specific branch.
 
 Details for point 6:
+
   - The PHYEX administrator checks the pull requests in the other applications (see [below](#tests))
   - The IAL integrator integrates the contribution on the arome specific branch
   - The PHYEX administrator
@@ -47,11 +47,12 @@ Details for point 6:
     - when asked by the IAL integrator, builds a new arome specific branch (see [below](#code-preparation))
     - when an arome specific branch is used in an official cycle, the arome specific branch is tagged accordingly
 
-## NORMAL WORKFLOW FOR A CONTRIBUTION DEVELOPED IN MESONH
+## Normal workflow for a contribution developed in MESONH
 
 The developer sends its pull request on the Méso-NH repository (the physics source code is embedded in the model source code).
 
 Integration details:
+
   - The Meso-NH integrator extracts, from the different pull requests, what concern the PHYEX repository and send a pull request on PHYEX based on a mesonh specific branch
   - The PHYEX administrator:
     - validates (see [below](#tests)) the contribution
@@ -60,16 +61,17 @@ Integration details:
     - when asked by the Meso-NH integrator, he builds a new mesonh specific branch (see [below](#code-preparation))
     - when a mesonh specific branch is used in an official release, the mesonh specific branch is tagged accordingly
 
-## NORMAL WORKFLOW FOR ANOTHER CONTRIBUTION
+## Normal workflow for another contribution
 
 Pull requests must be based on the master branch.
 
 The PHYEX administrator:
+
   - validates (see [below](#tests)) the contribution
   - integrates the contribution in the master branch
   - regularly, he tags a new (minor) version of the master branch
 
-## TESTS
+## Tests
 
 The source code must follow strict mnh\_expand directives (described in the [Coding Norms documentation](./CodingNorms.md)). The script verify\_mnh\_expand.py must be used to give an additional check.
 
@@ -81,7 +83,7 @@ In addition to the scientific validation, the following tests must give the same
 
 When possible, the new version of PHYEX must reproduce the old results (scientific modifications must be activated with namelist keys).
 
-## CODE PREPARATION
+## Code preparation
 
 The source code stored in the master branches must be usable by all the models. But these models can have contradictory constraints. To bypass this difficulty, the source code is preprocessed before being included in the compilation environment of each model.
 
diff --git a/docs/Offline.md b/docs/Offline.md
index 756bf2520..be8f806cb 100644
--- a/docs/Offline.md
+++ b/docs/Offline.md
@@ -1,13 +1,11 @@
-# OFFLINE documentation
+# PHYEX OFFLINE DOCUMENTATION
 
-## ABOUT THIS DOCUMENT
+## About this section
 
 This document is intended for persons who want to use PHYEX in an offline mode.
 Some offline test programs are provided with the package and a library suitable for use with python is also available.
 
-This document is written using the markdown language. With pandoc, it can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf).
-
-## COMPILATION
+## Compilation
 
 The build/with\_fcm directory contains a build system.
 This build system has two dependencies (installation is done automatically by the compilation script):
@@ -41,7 +39,7 @@ Something like this can be used:
 
 The last step will creates a directory (in $HOME/TESTPROGS) with a copy of your source code and the build system, builds the testprogs and executes them.
 
-## TEST PROGRAM
+## Test program
 
 ### Data generation
 
@@ -61,9 +59,9 @@ The different main\_\*.exe programs obtained by the compilation can be run. Each
 
 As described in [COMPILATION](#compilation).
 
-## PYTHON BINDING
+## Python bindings
 
-**TODO** This section must be written. Key ideas are:
+**TODO** This section (and code) must be written. Key ideas are:
 
   - ctypesforfortran
   - example
diff --git a/docs/PHYEX.md b/docs/PHYEX.md
index c209efd71..d0aff1389 100644
--- a/docs/PHYEX.md
+++ b/docs/PHYEX.md
@@ -1,10 +1,10 @@
-# PHYEX
+# PHYEX INTRODUCTION
 PHYsique EXternalisée
 
-## ABOUT THIS DOCUMENT
+## About this document
 
-This document is a general presentation of the PHYEX package.
-More specific documentation can be found:
+This document is a presentation of the PHYEX package.
+It is divided into different sections:
 
  - [Developer](./Developer.md): package organisation, how to contribute, coding norms
  - [Coding norms](./CodingNorms.md): coding norms
@@ -13,9 +13,10 @@ More specific documentation can be found:
  - [Plugging](./Plugging.md) : how to plug the physics package in a model
  - [Tools](./Tools.md): description of the check\_commit\_\*.sh scripts (to check bit reproducibility between two commits) and of the prep\_code.sh script
 
-This document is written using the markdown language. With pandoc, it can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf).
+This document is written using the markdown language. With pandoc, each md file can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf).
+In addition, the tools directory contains the generate\_standalone\_doc.sh script that can build a standalone pdf or html file.
 
-## HISTORY
+## History
 
 The physics was first developed for the [Meso-NH model](http://mesonh.aero.obs-mip.fr/).
 
@@ -23,7 +24,7 @@ Then, a part of the physics have been used to build the AROME model ([Seity et a
 
 The last evolution was to extract the physics to build the independent PHYEX package.
 
-## CONTENT
+## Content
 
 The following parametrisations are included in the PHYEX package (see the MesoNH documentation for references):
 
diff --git a/docs/Plugging.md b/docs/Plugging.md
index abd76b0d7..80fcebe1c 100644
--- a/docs/Plugging.md
+++ b/docs/Plugging.md
@@ -1,14 +1,12 @@
-# PHYEX plugging documentation
+# PHYEX PLUGGING DOCUMENTATION
 
-## ABOUT THIS DOCUMENT
+## About this section
 
 The PHYEX parametrisations can be called from the Meso-NH and AROME models, from
 test programs and from a driver.
 This document is intended for developers who want to plug in the physics in a new model or program.
 
-This document is written using the markdown language. With pandoc, it can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf).
-
-## INTERFACES
+## Interfaces
 
 The folowing routines are identified as the interface of the physics:
 
@@ -22,7 +20,7 @@ The folowing routines are identified as the interface of the physics:
 
 This interface is declared in the corresponding modi\_\* files.
 
-## HOOKS
+## Hooks
 
 The code provided in the common directory is independent, it can be compiled and used without
 dependency except the [fiat package](https://github.com/ecmwf-ifs/fiat).
diff --git a/docs/Tools.md b/docs/Tools.md
index dd2232e9f..6fb2df1d0 100644
--- a/docs/Tools.md
+++ b/docs/Tools.md
@@ -1,14 +1,12 @@
-# TOOLS DOCUMENTATION
+# PHYEX TOOLS DOCUMENATTION
 
-## ABOUT THIS DOCUMENT
+## About this section
 
 This document is intended for persons who want to use the prep\_code.sh or the check\_commit\_\*.sh scripts.
 
-This document is written using the markdown language. With pandoc, it can be converted to HTML (pandoc -s \<filename\>.md -o \<filename\>.html) or PDF (pandoc -s \<filename\>.md -o \<filename\>.pdf).
+## Installation, path...
 
-## INSTALLATION, PATH...
-
-Installation is covered in the [INSTALL documentation](../tools/INSTALL.md).
+Installation is covered in the [tools/INSTALL.md file](../tools/INSTALL.md).
 
 Environment variables can be set with:
 
@@ -16,7 +14,7 @@ Environment variables can be set with:
 . <git repository>/tools/env.sh
 ```
 
-## TOOLS
+## Tools
 
 ### check\_commit\_ial.sh
 
@@ -24,7 +22,7 @@ The check\_commit\_ial script compiles, executes IAL test cases and compare the
 
 Script options can be displayed with the -h option.
 
-Before being usable, the AROME model must be installed following the [INSTALL\_pack\_ial documentation](../tools/INSTALL_pack\_ial.md).
+Before being usable, the AROME model must be installed following the [tools/INSTALL\_pack\_ial.md file](../tools/INSTALL_pack\_ial.md).
 
 ### check\_commit\_mesonh.sh
 
@@ -32,7 +30,7 @@ The check\_commit\_mesonh.sh script compiles, runs a test case of the Meso-NH mo
 
 Script options can be displayed with the -h option.
 
-Before being usable, the mesonh model must be installed following the [INSTALL\_pack\_mesonh documentation](../tools/INSTALL_pack_mesonh.md).
+Before being usable, the mesonh model must be installed following the [tools/INSTALL\_pack\_mesonh.md file](../tools/INSTALL_pack_mesonh.md).
 
 For check\_commit\_mesonh.sh the following environment variables can be set:
 
@@ -48,12 +46,12 @@ This directory must exist.
 
 Script options can be displayed with the -h option.
 
-To be usable the check\_commit\_testprogs.sh script needs input data. The generation and installation of these data are described in the [INSTALL\_testprogs documentation](../tools/INSTALL_testprogs.md).
+To be usable the check\_commit\_testprogs.sh script needs input data. The generation and installation of these data are described in the [tools/INSTALL\_testprogs.md file](../tools/INSTALL_testprogs.md).
 
 The goal of the script is to compare outputs between two simulations (to check if bit-reproducibility is achieved or not).
 A reference simulation must be performed and save. This reference simulation is run the same way as the
 test experiment but cannot be compared to something else:
-check\_commit\_testprogs.sh -c -r <reference_commit>
+check\_commit\_testprogs.sh -c -r \<reference\_commit\>
 
 If this reference simulation must become the 'absolute' reference (used when invoking the check\_commit\_testprogs.sh
 script with the 'REF' argument), the reference simulation directory (under $TESTPROGSDIR) must be renamed 'ref'.
@@ -61,7 +59,7 @@ script with the 'REF' argument), the reference simulation directory (under $TEST
 ### prep\_code.sh
 
 This script is used by the different check\_commit\_\* scripts and can be used directly to pre-process the source code.
- The installation is described in the [INSTALL\_mnh\_expand documentation](../tools/INSTALL_mnh_expand.md)
+ The installation is described in the [tools/INSTALL\_mnh\_expand.md file](../tools/INSTALL_mnh_expand.md)
 
 ### others
 
@@ -72,3 +70,4 @@ Other scripts are:
   - correct\_indent.py: correct source code indentation in mnh\_expand blocs
   - diffNODE.001\_01: compare NODE.0001\_01 output files
   - verify\_mnh\_expand.py: check syntax in mnh\_expand blocs
+  - generate\_standalone\_doc.sh: to generate a standalone doc from the different md files
diff --git a/tools/generate_standalone_doc.sh b/tools/generate_standalone_doc.sh
new file mode 100755
index 000000000..e4f64f520
--- /dev/null
+++ b/tools/generate_standalone_doc.sh
@@ -0,0 +1,135 @@
+#!/bin/bash
+
+function usage {
+  echo "Usage: $0 [-h] output"
+  echo "output         output file with .pdf or .html extension"
+  echo "-h             to get this help"
+  echo
+  echo "This script builds a standalone documentation. The format of the documentation"
+  echo "is determined by the output file extension."
+  echo "The script has been tested with .pdf and .html extensions."
+  echo
+  echo "The script must be stored in the tools directory (to find the relevant md files."
+  echo "All the md files must begins with a uniq title line of first level (eg: '# title')"
+}
+
+#Script must be called with one argument: the output file to produce
+output=""
+while [ -n "$1" ]; do
+  case "$1" in
+    '-h') usage;;
+    *) if [ -z "${output-}" ]; then
+         output="$1"
+       else
+         echo "Only one argument is allowed, type $0 -h for help"
+         exit 97
+       fi;;
+  esac
+  shift
+done
+if [ -z "${output-}" ]; then
+  echo "Script must be called with the output file as first and only argument"
+  exit 98
+fi
+output="$(cd "$(dirname "${output}")" && pwd)"/$(basename $output)
+format=$(echo $output | rev | cut -s -d. -f1 | rev)
+
+#Ordered list of md files
+mdfiles="PHYEX.md Developer.md CodingNorms.md Integrator.md Offline.md Plugging.md Tools.md"
+
+#Resources needed
+resources="AROMEworkflow1.svg AROMEworkflow2.svg"
+
+#Script is assumed to be in the tools directory of PHYEX
+PHYEXTOOLSDIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ $(basename $PHYEXTOOLSDIR) != 'tools' ]; then
+  echo "The script must be put in the tools directory of the PHYEX package"
+  exit 96
+fi
+
+#Create a temporary directory and set it to be deleted at the end
+dir=$(mktemp -d ${TMP:-/tmp}/d.XXXXXX) || exit 99
+trap 'rm -rf "$dir"' EXIT
+
+#Copy files in this directory
+for file in $mdfiles $resources; do
+  cp $PHYEXTOOLSDIR/../docs/$file $dir/
+done
+
+#Move to tep dir
+cd $dir
+
+#Create helper files
+cat > rsvg-convert <<EOF
+#!/bin/bash
+#Comments from https://github.com/miyako/console-rsvg-convert
+#-d, --dpi-x=<float> pixels per inch [optional; defaults to 90dpi]
+#-p, --dpi-y=<float> pixels per inch [optional; defaults to 90dpi]
+#-x, --x-zoom=<float> x zoom factor [optional; defaults to 1.0]
+#-y, --y-zoom=<float> y zoom factor [optional; defaults to 1.0]
+#-z, --zoom=<float> zoom factor [optional; defaults to 1.0]
+#-w, --width=<int> width [optional; defaults to the SVG's width]
+#-h, --height=<int> height [optional; defaults to the SVG's height]
+#-f, --format=[png, pdf, ps, svg] [optional; defaults to 'png']
+#-o, --output=<path> output filename [optional; defaults to stdout]
+#-b, --background-color=[black, white, #abccee, #aaa...] set the background color [optional; defaults to None]
+#-u, --base-uri=<uri>
+#-v, --version show version information
+#
+#-u, --unlimited
+#-f, --format=[eps, xml, recording]
+#-a, --keep-aspect-ratio whether to preserve the aspect ratio [optional; defaults to FALSE]
+#--keep-image-data
+#--no-keep-image-data
+
+#We expect to receive
+#-f pdf -a -o output_file input_file
+
+if [ \$1 == '-f' -a \$2 == 'pdf' -a \$3 == '-a' -a \$4 == '-o' ]; then
+  convert \$6 \$5
+fi
+EOF
+chmod +x rsvg-convert
+
+if [ "$format" == 'pdf' ]; then
+  cat > titlesec.tex <<EOF
+\usepackage{sectsty} \sectionfont{\clearpage}
+
+EOF
+else
+  #normaly useless but toc is not displayed in html
+  #if option --include-in-header isn't set
+  touch titlesec.tex
+fi
+
+cat > title.md <<EOF
+---
+title: PHYEX (PHYsique EXternalisée)
+geometry: margin=2cm
+...
+EOF
+
+#Links between files
+#All the files must begin with a first level title, we get the correspondance
+declare -A sections
+for file in $mdfiles; do
+  if [ "$(head -1 $file | cut -c 1)" != '#' -o  "$(head -1 $file | cut -c 1-2)" == '##' ]; then
+    echo "All the md files must begin (first line) with a top level title (one and only one '#')"
+    echo "Please check $file file."
+    exit 95
+  fi
+  sections[$file]=$(echo $(head -1 $file | cut -c 2-) | sed -e 's/\(.*\)/\L\1/' | sed 's/ /-/g')
+done
+#We replace links to these files by links to anchors
+for mdfile in $mdfiles; do
+  for file in $mdfiles; do
+    sed -i "s/](.\/$file)/](#${sections[$file]})/g" $mdfile
+    sed -i "s/]($file)/](#${sections[$file]})/g" $mdfile
+  done
+done
+
+#Generate output file
+pandoc --toc --toc-depth=2 --number-sections \
+       --include-in-header titlesec.tex \
+       -o $output \
+       title.md $mdfiles
-- 
GitLab