diff --git a/docs/latex/cassiopee_doc_en.tex b/docs/latex/cassiopee_doc_en.tex new file mode 100644 index 0000000000000000000000000000000000000000..2fad7dd9589b0466cb705276eb42e6b129e905fc --- /dev/null +++ b/docs/latex/cassiopee_doc_en.tex @@ -0,0 +1,83 @@ +%******************************************************************************* +% @file cassiopee_doc_en.tex +% Modèle de documentation en anglais de Cassiopée, basé sur le modèle de rapport pour INRAE. +% À utiliser avec le modèle https://gitlab.irstea.fr/david.dorchies/latex_models +% @author David Dorchies, Mathias Chouet (INRAE Montpellier) +% @date Jan 2020 +%******************************************************************************* +\documentclass[12pt,a4paper,titlepage,twoside]{report} + + +% Insertion des différents préambules au document +\input{rapport/english/preambule_rapport_english} +\input{rapport_inrae/preambule_inrae} + + +%******************************************************************************* +%Données de titre et d'auteur pour la page de garde, les entêtes et pieds de page +%******************************************************************************* +% Le titre doit être relativement court mais assez explicite +\newcommand{\service}{UMR G-EAU} +\newcommand{\titre}{Cassiopée 4 software} +\newcommand{\sousTitre}{User documentation} +%Statut du document [rapport final, rapport intermédiaire] +% auteur intellectuel, rédacteur du document, il peut y avoir plusieurs auteurs ; chaque auteur est renseigné sous la forme « Prénom NOM » +\newcommand{\auteur}{David DORCHIES} +% date de validation du document (qui entraine sa diffusion)] +\newcommand{\dateValidation}{\today} +% Site INRAE +\newcommand{\site}{ + UMR G-EAU + + INRAE Montpellier +} +% Adresse du site +\newcommand{\adresse}{361 rue J-F Breton - BP 5095\\34196 Montpellier cedex 5} +% Téléphone et télécopie +\newcommand{\telephone}{tél. : +33(0)4670400} +% Sites internet +\newcommand{\website}{ + \url{www.g-eau.fr} \\ + \url{www.inrae.fr} +} + + +%******************************************************************************* + + +\begin{document} +%Supprime les veuves et orphelines +\widowpenalty=10000 +\clubpenalty=10000 +\raggedbottom + +% Integre la page de garde +%\input{title.tex} +\input{rapport_inrae/cover_inrae} +\input{rapport/headfoot_content} + +\cleardoublepage + +% Table des matières +\cleardoublepage +\tableofcontents + + +%******************************************************************************* +% Contenu de la documentation en anglais, généré par pandoc via mkdocs2pdf.py +%******************************************************************************* +\chapter{Documentation} +\input{cassiopee_doc_contents_en} + + +\chapter{List of figures} +\listoffigures +\listoftables + + +% 4ème de couverture +\cleartobackcover +\input{rapport_inrae/backcover_inrae.tex} + + +\end{document} diff --git a/docs/latex/cassiopee_doc_fr.tex b/docs/latex/cassiopee_doc_fr.tex new file mode 100644 index 0000000000000000000000000000000000000000..a34975a57bb42fe609c83067ea25779ba157695a --- /dev/null +++ b/docs/latex/cassiopee_doc_fr.tex @@ -0,0 +1,83 @@ +%******************************************************************************* +% @file cassiopee_doc_fr.tex +% Modèle de documentation en français de Cassiopée, basé sur le modèle de rapport pour INRAE. +% À utiliser avec le modèle https://gitlab.irstea.fr/david.dorchies/latex_models +% @author David Dorchies, Mathias Chouet (INRAE Montpellier) +% @date Jan 2020 +%******************************************************************************* +\documentclass[12pt,a4paper,titlepage,twoside]{report} + + +% Insertion des différents préambules au document +\input{rapport/francais/preambule_rapport_francais} +\input{rapport_inrae/preambule_inrae} + + +%******************************************************************************* +%Données de titre et d'auteur pour la page de garde, les entêtes et pieds de page +%******************************************************************************* +% Le titre doit être relativement court mais assez explicite +\newcommand{\service}{UMR G-EAU} +\newcommand{\titre}{Logiciel Cassiopée 4} +\newcommand{\sousTitre}{Documentation utilisateur} +%Statut du document [rapport final, rapport intermédiaire] +% auteur intellectuel, rédacteur du document, il peut y avoir plusieurs auteurs ; chaque auteur est renseigné sous la forme « Prénom NOM » +\newcommand{\auteur}{David DORCHIES} +% date de validation du document (qui entraine sa diffusion)] +\newcommand{\dateValidation}{\today} +% Site INRAE +\newcommand{\site}{ + UMR G-EAU + + INRAE Montpellier +} +% Adresse du site +\newcommand{\adresse}{361 rue J-F Breton - BP 5095\\34196 Montpellier cedex 5} +% Téléphone et télécopie +\newcommand{\telephone}{tél. : +33(0)4670400} +% Sites internet +\newcommand{\website}{ + \url{www.g-eau.fr} \\ + \url{www.inrae.fr} +} + + +%******************************************************************************* + + +\begin{document} +%Supprime les veuves et orphelines +\widowpenalty=10000 +\clubpenalty=10000 +\raggedbottom + +% Integre la page de garde +%\input{title.tex} +\input{rapport_inrae/cover_inrae} +\input{rapport/headfoot_content} + +\cleardoublepage + +% Table des matières +\cleardoublepage +\tableofcontents + + +%******************************************************************************* +% Contenu de la documentation en français, généré par pandoc via mkdocs2pdf.py +%******************************************************************************* +\chapter{Documentation} +\input{cassiopee_doc_contents_fr} + + +\chapter{Table des illustrations} +\listoffigures +\listoftables + + +% 4ème de couverture +\cleartobackcover +\input{rapport_inrae/backcover_inrae.tex} + + +\end{document} diff --git a/docs/latex/logo_pole.png b/docs/latex/logo_pole.png new file mode 100644 index 0000000000000000000000000000000000000000..8c1038067c2e83d700a7161574829742dd2e321b Binary files /dev/null and b/docs/latex/logo_pole.png differ diff --git a/docs/latex/logos.tex b/docs/latex/logos.tex new file mode 100644 index 0000000000000000000000000000000000000000..7e5bc30689dce23851298f8e64acc97899ccdab5 --- /dev/null +++ b/docs/latex/logos.tex @@ -0,0 +1,14 @@ +% Example of logos layout for page "cover_inrae.tex" + +\hfill +\includegraphics[width=8cm]{logo_pole.png} + +\vspace{3mm} + +\hfill +\includegraphics[width=4cm]{rapport_inrae/logo_inrae_couv_haut.png} + +\vspace{3mm} + +\hfill +\includegraphics[width=4cm]{rapport_inrae/logo_geau.png} diff --git a/mkdocs2pdf.py b/mkdocs2pdf.py index d25414e10148f7bbb8fcd24db79309d3469c8677..cc27bab227faed6cd66224d4230891a9a7cc2ca3 100644 --- a/mkdocs2pdf.py +++ b/mkdocs2pdf.py @@ -14,17 +14,32 @@ # - python3 ./mkdocs2pdf.py # -outputDir = 'docs/fr/pdf' -filename = 'cassiopee_docs-fr' +import os +import sys +import yaml +import re +import shutil +baseDir = os.getcwd(); + +buildDir = os.path.join(baseDir, 'docs/pdf_build') +outputDir = os.path.join(baseDir, 'src/assets/docs/pdf') + +latexModelDir = 'latex_models' +modelDir = os.path.join(buildDir, latexModelDir) + +mergedDocFilenamePrefix = 'cassiopee_doc_contents_' +filenamePrefix = 'cassiopee_doc_' + +latexModelRepository = 'https://gitlab.irstea.fr/david.dorchies/latex_models.git' + +# Reads an MkDocs configuration file def readConfig(sYAML): f = open(sYAML, 'r') with f: try: - import yaml dMkdocsYaml = yaml.load(f, Loader=yaml.SafeLoader) except yaml.YAMLError as e: - import sys sys.exit("ERROR on YAML loading {}: {}".format(sYAML, str(e))) return dMkdocsYaml @@ -32,7 +47,6 @@ def getMdHeader(title, level): return "#" * level + " " + title + "\n" def shiftMdHeaders(mdContent, level): - import re if level == 0: return mdContent @@ -44,20 +58,21 @@ def shiftMdHeaders(mdContent, level): lMd[i] = ("#" * level) + item return "\n".join(lMd) -def explore(docs_dir, nav, output = '', level = 0): +# Browses MkDocs configuration file and merges .md files +def exploreAndMerge(docs_dir, nav, output = '', level = 0): """ @param docs_dir path to the mkdocs content files - @param dictionnary with the structure to explore + @param nav dictionnary with the structure to explore @param output markdown files content already merged """ - import os, re if type(nav) is str: nav = [nav] for d in nav: if type(d) is str: filepath = os.path.join(docs_dir, d) f = open(filepath, 'r') - path = os.path.join('..', os.path.dirname(filepath)) + # Triple "../" because file will be compiled from pdf_build/latex_models + path = os.path.join('../../..', os.path.dirname(filepath)) s = f.read() + "\n" # Modification of image and links paths s = re.sub(r'(\!\[.+\]\()(.+)(\))', r'\1'+path+r'/\2\3', s) @@ -70,31 +85,20 @@ def explore(docs_dir, nav, output = '', level = 0): for key, value in d.items(): if type(value) is list: output += "\n" + getMdHeader(key, level) + "\n" - output = explore(docs_dir, value, output, level) + output = exploreAndMerge(docs_dir, value, output, level) level -= 1 return output - -if __name__ == '__main__': - - # Read config - dMkdocsYaml = readConfig('mkdocs.yml') - # Create string with merged MarkDown - s = explore(dMkdocsYaml['docs_dir'], dMkdocsYaml['nav']) - # Save the md file - import os - os.makedirs(outputDir, exist_ok=True) - OutputPath = os.path.join(outputDir, filename) - with open('{}.md'.format(OutputPath), 'w') as f: - f.writelines(s) - # Convert to tex format +# Creates a filePath.tex LaTeX contents file based on filePath.md +def convertMdToTex(filePath): + # Convert .md to .tex os.system( - 'pandoc {0}.md -f markdown -t latex -s -o {0}.tex'.format(OutputPath) + 'pandoc {0}.md -f markdown -t latex -s -o {0}.tex'.format(filePath) ) # Remove header of tex file bContent = False ls = [] - with open('{}.tex'.format(OutputPath), 'r') as f: + with open('{}.tex'.format(filePath), 'r') as f: for line in f: if line.strip() == '\\end{document}': bContent = False @@ -106,9 +110,100 @@ if __name__ == '__main__': for i, line in enumerate(ls): ls[i] = line.replace('\\includegraphics', '\\includegraphics[max size={\\textwidth}{0.9\\textheight}]') - with open('{}.tex'.format(OutputPath), 'w') as f: + with open('{}.tex'.format(filePath), 'w') as f: f.writelines(ls) +def getLatexModel(): + # Clone Git repository + os.chdir(buildDir) + os.system( + 'git clone {} {}'.format(latexModelRepository, latexModelDir) + ) + # back to original working drectory + os.chdir(baseDir) + +# Inject generated merged documentation and necessary resources (template, logos…) +# into LaTeX models directory by symlinking them +def injectContentIntoModel(mergedDocFilenameTex, lang): + """ + @param mergedDocFilenameTex filename of the generated LaTeX merged doc, with its .tex extension, without directory + @param lang language; used to inject content in the right template + """ + # Symlink necessary resources + os.chdir(modelDir) + relPathToMergedTexDoc = os.path.join('..', mergedDocFilenameTex) + os.system( + 'ln -s {} .'.format(relPathToMergedTexDoc) + ) + latexTemplate = 'cassiopee_doc_' + lang + '.tex' + relPathToLatexTemplate = os.path.join('../../latex', latexTemplate) + os.system( + 'ln -s {} .'.format(relPathToLatexTemplate) + ) + os.system( + 'ln -s ../../latex/logo_pole.png .' + ) + os.system( + 'rm rapport_inrae/logos.tex' + ) + os.system( + 'ln -s ../../../latex/logos.tex rapport_inrae/' + ) + # back to original working drectory + os.chdir(baseDir) + +# Build a PDF file from the LaTeX source +def buildPDF(lang): + # Compile LaTeX source + os.chdir(modelDir) + sourceTexFile = 'cassiopee_doc_' + lang + '.tex' + outputPdfFile = 'cassiopee_doc_' + lang + '.pdf' + os.system( + 'latexmk -f -pdf -interaction=nonstopmode {} > /dev/null 2>&1'.format(sourceTexFile) + ) + # copy generated PDF to release directory + shutil.copy(outputPdfFile, outputDir) + # back to original working drectory + os.chdir(baseDir) + +# Creates the PDF documentation file for the given language +def buildDocForLang(lang): + + # Prepare temporary build directory + os.makedirs(buildDir, exist_ok=True) + # Prepare output directory + os.makedirs(outputDir, exist_ok=True) + + # Read config + yamlPath = 'mkdocs-' + lang + '.yml' + print("yamlPath: " + yamlPath) + dMkdocsYaml = readConfig(yamlPath) + + # Create string with merged MarkDown + s = exploreAndMerge(dMkdocsYaml['docs_dir'], dMkdocsYaml['nav']) + # Save the merged .md file + mergedDocFilename = mergedDocFilenamePrefix + lang + print("filename: " + mergedDocFilename) + mergedDocOutputPath = os.path.join(buildDir, mergedDocFilename) + with open('{}.md'.format(mergedDocOutputPath), 'w') as f: + f.writelines(s) + + # Convert to tex format + convertMdToTex(mergedDocOutputPath) + + # Get INRAE report LaTeX model and inject merged content inside + getLatexModel() + injectContentIntoModel(mergedDocFilename + '.tex', lang) + + # Build PDF from LaTeX source + buildPDF(lang) + + # Clean build dir + shutil.rmtree(buildDir) + + +if __name__ == '__main__': -# latexmk -f -pdf -interaction=nonstopmode rapport_inrae.tex -# latexmk -c \ No newline at end of file + for l in ['fr', 'en']: + print('building PDF doc for language "{}"'.format(l)) + buildDocForLang(l)