Add script to convert markdown docs for support in xwiki (#973)

.gitignore

@@ -53,6 +53,7 @@ coverage-reports
 # Doc pdf file
 antaresxpansionuserguide.pdf
 include/google/protobuf/message.h
+xwiki_source
 
 # vscode
 .vscode

docs/pdf-doc-generation-with-sphinx/create_xwiki_doc.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# This script can be useful to modify the markdown source files of the docs used by mkdocs to a format that can be (almost) correctly formatted with xWiki in markdown mode. The main modifications are to replace the following :
+# Inline math : \\( ...some math... \\) with the mathjax macro {{mathjax}} ...some math... {{/mathjax}}
+# Display mode math : $$ ...some math... $$ with the mathjax macro and an equation environement {{mathjax}}\begin{equation*} ...some math... \end{equation*}{{/mathjax}}
+# Special characters that are managed differently within mkdocs and xWiki
+
+# copy reference guide md files and assets
+rm -rf xwiki_source/user-guide
+cp -r ../user-guide xwiki_source/
+cp -r ../assets/ xwiki_source/
+cp ../index.md xwiki_source/user-guide/
+
+# change style for inline latex math \\( -> {{mathjax}} and \\) -> {{/mathjax}}
+find xwiki_source/user-guide/ -type f -name "*.md" -exec sed -i 's=\\\\)=\\)\{\{/mathjax\}\}=g ; s=\\\\(=\{\{mathjax\}\}\\(=g' {} \;
+
+# change style for display latex math \n$$ -> {{mathjax}}\begin{equation*} and $$\n -> \end{equation*}{{/mathjax}}
+find xwiki_source/user-guide/ -type f -name "*.md" -exec perl -0777 -pi -e 's/(\s*)\$\$\n\s*\n/\1\\end{equation*}\1\{\{\/mathjax}}\n\n/g; s/\n\n(\s*)\$\$/\n\1\{\{mathjax}}\n\1\\begin{equation*}/g' {} \;
+
+# Replace \\{ with \{ 
+find xwiki_source/user-guide/ -type f -name "*.md" -exec sed -i 's=\\\\{=\\\{=g ; s=\\\\}=\\\}=g' {} \;
+
+# Replace \\\\ with \\
+find xwiki_source/user-guide/ -type f -name "*.md" -exec sed -i 's=\\\\\\\\=\\\\=g' {} \;
+
+# Replace \_ (used in mkdocs to avoid confusion with italic) with _ for latex/xWiki
+find xwiki_source/user-guide/ -type f -name "*.md" -exec sed -i 's=\\_=_=g' {} \;
+
+# # clean
+# To be run once the content of the files within xwiki_source/user-guide has been copied (manually) to xWiki
+# rm -rf xwiki_source/user-guide

docs/user-guide/optimization-principles/problem-formalization.md

@@ -132,7 +132,7 @@ $$
 $$
 
 This problem can be linearized by introducing continuous variables \\(\vartheta_{l, s} \in \mathbb{R}\\) for \\(l \in [1, N]\\) and \\(s \in [1,52]\\), which gives rise to an equivalent reformulation of the investment problem, known as the Benders reformulation or _Benders master problem_:
-    
+
 $$
 \begin{aligned}
     \min\_{x \in \mathcal{X}}\ & c^{\top}x + \sum_{l=1}^{N} p_{l} \sum_{s=1}^{52} \vartheta_{l, s} \\\\